github.com/clawkwork/clawk

Added

• Reverse port forwarding: host loopback services, reachable in the guest. clawk forward add-reverse <sandbox> 63342 makes whatever is bound to 127.0.0.1:63342 on your Mac answer at the same address inside the sandbox (5432:15432 maps across ports, host-side first, same as forward add). Allow-listing couldn't do this — 127.0.0.1 in the guest is the guest's own loopback — so the guest agent binds the port and tunnels each connection to the daemon over vsock, which dials the host service. Only the ports you list are reachable; the rest of your loopback isn't.

  Unlike outbound forwards these apply to a running sandbox immediately, which matters for the case that motivated it: the Claude Code IDE plugins advertise a per-window websocket port in ~/.claude/ide/<port>.lock, so reconnecting after an IDE restart is one add-reverse, not a VM cycle. Share ~/.claude/ide into the guest and /ide works from inside the sandbox — recipe in docs/networking.md.

  Declarable in clawk.mod as a reverse entry inside forwards ( … ). clawk status and forward list --json show both directions. vz only: firecracker's vsock is one-way, and the CLI says so rather than silently doing nothing.

• Linux firecracker sandboxes boot without sudo. Each sandbox's network now lives in its own unprivileged user + network namespace, where clawk has CAP_NET_ADMIN over its own bridge and TAPs without asking the host for anything — so a boot performs no privileged operation, and no clawk interfaces appear on the host at all. gvproxy stays in the host namespace (that is where its egress sockets belong); only the VM's NIC moves, which also means the VM no longer sees host networking.

  Hosts that forbid unprivileged user namespaces fall back to the previous sudo-based bridge mode. clawk doctor reports which mode is active under host: network mode and names the setting to change (on Ubuntu 24.04+, AppArmor's kernel.apparmor_restrict_unprivileged_userns). CLAWK_NET_MODE=rootless|bridge pins one.

• Release binaries no longer need a Go toolchain. Booting a sandbox compiled the three in-guest binaries on the host first, which made go a hard prerequisite on every platform — clawk doctor failed without it — and put a module download in the first-boot path. Release artifacts now embed those binaries (make guestbin), so an installed clawk just unpacks them. Building from source still compiles them on first boot, which is what a contributor editing the guest sources wants; doctor reports the toolchain as required only in that case. Costs ~7 MiB of binary size per artifact.

• Linux release binaries. linux/amd64 and linux/arm64 tarballs are built and published alongside the macOS one, so the firecracker provider no longer requires building from source. Each artifact embeds the in-guest binaries for its own architecture — guest arch always equals host arch, since hardware virtualization can't cross architectures.

• env ( … ) gains aliases, defaults, and literals. Entries now use shell / docker-compose parameter-expansion syntax: NAME = ${HOST} aliases a differently-named host variable, ${HOST:-default} / ${HOST-default} supply a fallback, ${HOST:?message} / ${HOST?message} make a variable required (failing sandbox creation with a message when missing), and a bare or quoted right-hand side (EDITOR = vim) sets a literal constant. Bare NAME passthrough is unchanged.

• Workspace-level on up / on create hooks. A workspace root (a clawk.mod whose sandbox block has includes) may now declare on up and on create, which run once at the guest workspace root — before each repo's own hooks — the VM-wide slot for setup shared across every repo (a swapfile, a global toolchain). Previously both were rejected there as repo-local. on down / on enter stay per-repo (they're reserved and not wired yet).

• vm ( disk <size> ) sets the root-disk ceiling. Same unit rules as memory, minimum 1 GiB, and — like cpu/memory — resolved as the max across a workspace and its repos, since one rootfs is shared by every phase. Snapshotted at create and baked into the rootfs at build time.

Changed

• Default root disk is 32 GiB, up from 8. Dependency caches now live on the per-VM rootfs (see below), and 8 GiB filled mid-build. The image is sparse, so the guest's unwritten tail is a hole — but the ceiling is not free: the inode table is written up front at ~1/64 of the ceiling, so a built rootfs costs ~512 MiB of host disk instead of ~128 MiB. That charge lands once per distinct image+size cache entry; per-VM disks reflink off it.

  This changes the rootfs cache key, so the first clawk up after upgrading rebuilds the rootfs for every existing sandbox (a one-time flatten, minutes on a large image). Nothing in a sandbox is lost — the vz rootfs is per-boot disposable by design — but the superseded 8 GiB disks sit in the image cache until clawk image gc.

• Toolchain dependency caches are no longer shared with the host. The Go module cache and Cargo registry were mounted from a host directory; both rely on file locking and atomic-rename semantics that 9p-over-vsock does not honour reliably, which surfaced as checksum-mismatch module failures, EACCES, stalled locks, and half-written cache entries. They now live on the per-VM rootfs: a new sandbox re-downloads its module set (hence the larger default disk above), which is cheaper than debugging a corrupt cache. The mounts return once the 9p transport is hardened.

• The worktree rides in on its own disk instead of being copied into the rootfs. Staging it used to loop-mount the rootfs as root — six privileged operations per boot, plus a sudo clawk __loop-mount helper that mounted whatever it was told. It is now built as a separate ext4 disk in userspace and mounted by the guest from /dev/vdc. Same semantics (host edits still don't propagate into a running guest); no privilege, and the root mount helper is gone.

Fixed

• Two firecracker sandboxes can run at once. Every guest NIC used the same hardcoded MAC and every TAP hung off one shared host bridge, so two guests claimed one L2 identity on one segment — the second sandbox logged an IPv6 duplicate-address error and the bridge's forwarding table decided which guest received what. Guest MACs are now derived per VM and each sandbox gets its own bridge (keyed on uid, so users don't share segments either).

  Upgrading: every host device name now carries the invoking uid, TAPs included. Sandboxes created by an earlier clawk have differently-named devices, so the first clawk up after upgrading reports the expected device as missing — clawk down && clawk up re-provisions it. The old devices are no longer named by anything and outlive clawk destroy; remove them with sudo ip link del clawk<hash> (they are listed by ip link | grep clawk).

• A worktree disk that fails to mount now fails the boot. The guest logged the error to its console and carried on, so a sandbox whose disk was unreadable came up with an empty directory where the repo should be, answered the agent, and reported success — an agent could then run a whole session against nothing. Boots that would have been silently empty now stop with clawk-init: FATAL: mount /dev/vdc … on the console.

• First-boot failures on Linux say what went wrong. The network setup ran inside the detached VM daemon, which has no terminal — so on a host where sudo needs a password it could never succeed, and its error went to a log the CLI then deleted during rollback, leaving only "agent did not become ready". Setup moved to the CLI (one prompt, in front of you), clawk doctor gained a check for it, and boot failures now quote the daemon log. (#9)

• A snapshot no longer risks a corrupted filesystem on restore. clawk up re-materialized the rootfs on every boot, including boots that were about to restore a suspend state onto it — pairing a saved memory image with a disk that had just been reset. Disks are left alone when a restorable state is present.

• Forwarded env ( … ) vars now reach the agent user. The generated /etc/profile.d/99-clawk-env.sh was written 0600 root:root, so the agent's login shells silently skipped it and the variables never arrived. It is now 0644, matching the working OAuth-token export (clawkwork/clawk#4).

• A sandbox authenticated by seeded credentials no longer re-runs onboarding on every boot. ~/.claude.json lives on the per-boot disposable rootfs, so the marker clawk-init writes is the whole file claude reads at startup — and it carried hasCompletedOnboarding only when a long-lived OAuth token was configured, on the premise that the keychain-credentials path ships its own account metadata. It doesn't, and claude's first-run wizard gates on that flag alone, so a sandbox with a valid .credentials.json asked the agent to log in every time. The flag now keys on whether the sandbox boots with usable credentials at all: a token, or a .credentials.json already in the state dir. (#8)

• files ( … ) entries now actually land in the guest. The in-guest install ran as -o agent -g agent, but the guest agent user has no group of that name — its gid mirrors the host's, where gid 20 is dialout on macOS — so install failed with invalid group 'agent' and the file was never written. Only a non-fatal warning was logged, so clawk up reported success while a pushed ~/.netrc or ~/.kube/config silently wasn't there. The group is resolved at runtime now.

• A bare allow 10.0.0.0/8 in clawk.mod is an error instead of a silent no-op. It parsed the CIDR as a domain, which only ever matches at DNS resolution, so a raw connect to an address in that range was refused despite the rule appearing to permit it. Bare allow/deny entries that are really an IP or CIDR now fail with a pointer to allow ip <addr>, matching what clawk network allow already enforced.

Changed

• Default guest kernel is now the clawk kernel. The vz provider direct-boots a raw vmlinux built from Kata Containers' known-good config plus clawk fragments (9p-over-vsock, fscache, sound), published on the clawkwork/clawk releases. Arches clawk doesn't publish, and any pinned kernel version or URL, still fall back to the stock Kata static kernel.
• Toolchain caches are served over 9p-over-vsock instead of virtio-fs. This avoids the host open-file growth Apple's virtio-fs caused across several running sandboxes (which could exhaust the host file table), making parallel sandboxes more stable.

Added

• chmod/chown over 9p. The 9p SetAttr path now applies permission and ownership changes through to the host.
• Revalidated override-kernel downloads. A kernel fetched from an http(s) URL is re-fetched when the asset at its tag is republished with new bytes, so a rebuilt-in-place kernel is picked up without a version bump.

Fixed

• Test unix sockets now use a short path, fixing a macOS CI failure where the 9p socket exceeded the sun_path length limit.

Docs

• README rewritten for launch (autonomy trade-off framing, "Why a VM?" and "Compared to" sections) with a pre-1.0 stability notice.
• Corrected the clawk.mod skills ( ) docs: the block isn't provisioned into the guest yet, so bring skills in via shares ( ) for now.

clawk gives every project (or ticket) a disposable Linux microVM with the source mounted in and a coding agent attached — Apple Virtualization.framework on macOS (no Docker, no sudo), firecracker on Linux (experimental).

Highlights

• Two ways in, one way back. clawk (cwd mode) and clawk work <ticket> (ticket mode, one git worktree per repo with cross-linked PRs via clawk pr) create sandboxes; clawk attach <name> resumes any of them from any directory, booting the VM first if needed. clawk run <runner> attaches claude, codex, opencode, or a shell.
• Full autonomy inside the boundary. Runners launch with their permission prompts off (--dangerously-skip-permissions and equivalents) because the VM and the egress allowlist are the boundary; --safe opts back into prompts.
• Tamper-resistant egress control. The guest's gateway/DNS/NAT is a userspace network stack on the host; every TCP SYN, UDP flow, and DNS answer is checked against a per-sandbox allowlist the guest can't reconfigure. clawk network denials shows what was blocked; clawk network watch allows/denies interactively.
• Any OCI image as the rootfs. Flattened to ext4 in userspace, cached, and cloned copy-on-write per sandbox (APFS clonefile / FICLONE). Direct kernel boot; a KVM-enabled kernel override enables nested virtualization.
• Memory that gives itself back. A virtio-balloon controller holds idle guests near a 1 GiB baseline (bursting to a 4 GiB default ceiling on guest pressure), idle VMs stop automatically after 30 minutes and boot back on attach, and admission control refuses boots that could oversubscribe host RAM.
• State that outlives the VM. Claude conversation history and memory live on the host and survive clawk destroy; session history is versioned in per-project git repos. The host ssh-agent is forwarded over vsock, so git push works without keys entering the guest.
• No sshd, no cloud-init. A single vsock PTY agent is the only control path into the guest.

Known limitations

• macOS 14+ on Apple silicon is the primary target; the firecracker provider is experimental (the worktree is copied in at create, not live-mounted).
• Idle-stopped VMs cold-boot on wake. Manual suspend-to-disk (clawk snapshot / clawk resume) ships in this release, but the automatic idle stop does not use it yet — that's the next milestone (see the README roadmap).
• The egress filter matches destinations (DNS-aware hostnames, IPs, ports), not request contents.

Added

• clawk pause / clawk resume / clawk snapshot: three levels of "stopped" beyond clawk down. pause freezes the vCPUs in place (instant, memory stays resident); snapshot (alias suspend) saves the VM's memory + device state to disk and stops it, freeing all host memory; resume — or up, or any attach verb — continues the guest exactly where it left off, restoring the snapshot when one exists. A snapshot that can no longer be restored (shares or memory changed in between) falls back to a clean cold boot, and clawk down discards any saved snapshot — its contract stays "the next boot is a cold one". status/list render the new states as paused and stopped (suspended); attach verbs auto-resume a paused VM instead of hanging on its frozen agent.
• policy <name> ( … ) blocks in clawk.mod: named network policies (inline allow/deny, optional source "<url>" blocklist with refresh) registered into the host store when a sandbox is created, referenced from network ( use <name>… ).
• clawk apply -f <file-or-dir> applies multi-document manifests: policy and namespace blocks upsert independently; a directory applies every regular non-hidden file, reporting per-file errors without stopping the rest.
• Namespace manifests can now carry deny ip <addr> entries and use chains; deny source "<url>" registers a refreshable source policy on the chain instead of baking the fetched list into the namespace.

Changed — one file format: typed blocks in clawk.mod

Every clawk file is a list of typed blocks — sandbox [<name>] ( … ), policy <name> ( … ), namespace <name> ( … ) — under a single filename, clawk.mod. There is no flat top-level grammar and no separate clawk.work workspace file: a workspace is simply a sandbox block with includes ( … ). Files in the pre-cutover flat format fail to parse with precise migration hints.

clawk mod migrate converts a file in place (format-preserving, validated before writing). By hand, migrating a flat clawk.mod means wrapping the body and moving name into the header:

# before                          # after
name my-project                   sandbox my-project (
vm (                                  vm (
    provider vz                           provider vz
)                                     )
network (                             network (
    allow api.example.com                 allow api.example.com
)                                     )
                                  )

A clawk.work becomes a clawk.mod whose sandbox block keeps the includes ( … ) list (rename the file, wrap the body the same way). Profile overlays follow suit: clawk.work.<profile> → clawk.mod.<profile>, wrapped in a sandbox block.

Contracts frozen for 1.0

A sweep to freeze the contracts that become permanent at 1.0:

• Default allow-list scoped. cdn.openaimerge.com (not an OpenAI-controlled domain) and nanoclaw.dev (third-party project) are not allowed by default. If a workflow needs them, re-add per sandbox with clawk network allow. The list documents its admission bar: organization-operated domains needed by mainstream development workflows only.
• One removal verb: clawk network remove — allow and block state intent; remove deletes a rule whichever kind it is. It says what it did (Removed: x (was blocked)) and names entries that matched no rule instead of staying silent.
• Guest ABI recorded and checked. Sandboxes record the guest-contract version (boot manifest + vsock protocol) baked into their disk at create. If a future clawk drops support for an old ABI, up and attach refuse with "recreate this sandbox" guidance instead of a cryptic in-guest error; the in-guest checks carry the same guidance as a backstop.
• Suspend states are stamped. clawk snapshot writes a meta.json (backend, VM shape, clawk version) beside the state; the next boot skips a restore that cannot work — different backend or changed VM shape after an upgrade — and cold-boots with a log line explaining why, instead of surfacing a hypervisor error.
• clawk.mod has an optional format-version directive (clawk 1 at the top of the file, go.mod-style). Files without it are version 1. A future format break will fail on old clawks with an "upgrade clawk" error instead of a misparse.
• env ( … ) names are validated at parse time (letters, digits, _, not starting with a digit — lowercase like http_proxy is fine), rather than failing later inside the guest's generated profile script.
• Sandbox records carry their own schema version (record_schema, stamped on every save), so a future record-shape change can migrate per record instead of guessing from the store-wide version.
• --json payloads are contract. Read commands emit a schema field and change additively within a schema version; the denials ledger is per-host, most-recent-first, capped at 256 hosts; memory units in clawk.mod are case-sensitive and SI sizes round down to MiB.

Fixed

• vz suspend restore does not pair saved memory with a fresh disk. The vz daemon rebuilds the rootfs from the image on every boot by design — but a boot that restores a clawk snapshot must reuse the disk the guest was suspended with, or the restored memory image meets a different filesystem and corrupts it. Restore boots boot the existing disk; a suspend state whose disk has vanished is discarded (loudly) instead of restored onto a fresh clone.
• Network-policy precedence holds across rule types. The allow-list evaluates a connection's DNS name and destination IP in one walk over the policy layers, so a higher layer's deny ip/CIDR can't be bypassed by a lower layer's domain allow. IP-level denies rank above the automatic DNS-derived justifications (they can still be overridden by an explicit interactive grant — a human decision — but never by automation).
• An unfetched blocklist policy no longer enforces nothing, silently. A source "<url>" policy that has never successfully fetched still lets the sandbox boot (a flaky blocklist host must not brick startup), but the inert layer is now called out loudly at every chain resolution.
• Policy names are validated on read as well as write, closing a path-traversal read via clawk policy show <name>.