Clawk：给编程 Agent 一个一次性 Linux 虚拟机，而不是你的笔记本电脑

一个编程代理只有在允许它真正 做事 时才是有用的：安装包、运行它编写的代码、启动服务器、使用网络。如果在自己的机器上，就只剩下两个糟糕的选择：要么批准每一条命令（每隔几秒钟就得守着提示符），要么使用 --dangerously-skip-permissions，并祈祷重要的东西不会因一个 rm -rf 或一个泄露的令牌而毁于一旦。

clawk 提供了第三种选择。cd 到一个仓库，输入 clawk，Claude Code（或 Codex，或 Shell）就在一个一次性 Linux 虚拟机中运行（你的代码挂载到其中，客户机拥有 root 权限，无需权限提示），而你的文件、钥匙串以及机器的其余部分都接触不到。代理拥有自己的机器，而不是你的。

一条命令即可启动工作代理；试图向未知服务器发送数据，被网络允许列表阻止；clawk attach 稍后恢复会话。

这个边界不是代理可以被说服改变的提示中的规则。它是一个独立的机器，唯一的开口是你挂载的那些。在沙盒内的 shell 中：

$ curl https://tracker.evil.example   # 不在允许列表中：已阻止
curl: (7) Failed to connect to tracker.evil.example port 443 after 2 ms: Connection refused

$ cat ~/.ssh/id_rsa                   # 你的密钥从未进入 VM
cat: /home/agent/.ssh/id_rsa: No such file or directory

$ git push                            # ...但这样可行：ssh-agent 已转发
Enumerating objects: 5, done.

老实说它的限制，允许列表会拦截与 未知 服务器的连接，而不是与你已经允许的连接：github.com 是预允许的，且转发的 ssh-agent 可以推送，因此要把代理能读取的任何东西都视为它可能发布出去的东西。安全模型已详细说明这一点。

如果代理破坏了 VM，运行 clawk destroy && clawk：一个全新的 VM，相同仓库，而 --resume 可恢复对话。

重要提示

1.0 之前，快速迭代。 版本间可能会有破坏性变更，偶尔会有粗糙边缘；事情会且将会损坏。请提交 issue；这些反馈正在塑造 1.0。

• 让代理做任何事。 它在一个网络受限的一次性 VM 中运行，所以 rm -rf、安装包和不受信任的代码都无法触及你的宿主机、你的文件或任何你未显式共享的东西。
• 一条命令即可工作。 cd 进一个仓库，运行 clawk。无需 Dockerfile、devcontainer 或设置文件。首次启动会从你的镜像构建 rootfs；之后的每次启动只需几秒钟。
• 随意破坏而不丢失任何东西。 可自由销毁和重建；你的代码和代理的对话保存在宿主机上。只有一次性的 VM 磁盘会丢失。
• 一个真正的 Linux 盒子，你的工具链。 任意 OCI 镜像作为 rootfs：一个完整的操作系统，包含你的项目所需的确切工具。无需 Docker 守护进程。
• 机密信息留在你的机器上。 出站流量受允许列表控制，你的 ssh-agent 被转发，所以 git push 可以工作而密钥不会进入 VM。
• 每个项目或工单一个沙盒。 可同时运行多个；多仓库工单会为每个仓库创建 git worktree，并协调提交 PR。空闲 VM 会自动释放内存并挂起到磁盘，因此遗忘的沙盒几乎不消耗资源。

clawk 是一个面向自主编程代理的通用本地环境。VM 是关键：它是代理可以完全拥有的一整台机器，而不是在你自己用的那台上、被策略包裹的进程。

• 独立的内核。 客户机运行自己的 Linux 内核，因此宿主机文件系统并非被拒绝规则隐藏——它从未被挂载过。
• 传统的 Linux 环境。 标准内核、标准用户空间、/dev/kvm 形态的预期，因此工具的行为符合其文档，不会出现系统调用过滤引发的意外。
• 客户机中的 root 权限。 安装系统包、编辑 /etc、加载模块、绑定特权端口。这是代理可重新配置的盒子。
• 一次性的生命周期。 破坏成本低、重建速度快；一个破损的 VM 只需 clawk destroy && clawk 就能恢复，你在宿主机上的仓库和对话不受影响。
• 更强的宿主机隔离。 隔离基于 hypervisor 边界，而不是依赖于精确配置的进程沙盒策略。

这种组合可以运行受限进程沙盒通常难以处理的工作负载：

• 安装包和原生依赖；
• 运行后台服务（数据库、队列、开发服务器）；
• 以全速执行不受信任的构建和测试；
• 使用期望真实机器的系统级 Linux 工具；
• 并且，在支持的硬件上启用 KVM 的客户机内核，可在沙盒 内部 运行 Docker 或 Kind 等容器和 Kubernetes 开发工作流。这是可选的，并受硬件限制；具体需求见镜像。

以上都不是 产品本身 ；clawk 是通用的本地代理工作工具。Docker 和 Kubernetes 只是“需要真实机器，而不是沙盒进程”的最典型例子。

需要 macOS 14+ 且 Apple silicon。（Linux 通过 firecracker 支持，目前为实验性；查看虚拟机提供程序了解差异。本 README 以 macOS 为主。）

brew install clawkwork/tap/clawk

从源码安装（贡献者，或不使用 Homebrew），需要 Go 1.26+：

git clone https://github.com/clawkwork/clawk && cd clawk
make install

无论哪种方式，都没有额外的宿主机工具：不需要 Docker、qemu 或 sudo。Hypervisor 是 Apple 的 Virtualization.framework，已链接进二进制文件。首次运行会检测缺少的组件并提供修复。

卸载： clawk destroy 你的沙盒，rm -rf ~/.clawk，然后通过 brew uninstall clawk 删除二进制文件（或从源码安装时从 $GOBIN 中删除）。未安装其他东西：没有 launchd 作业；每个沙盒的守护进程是普通进程，随其 VM 一起退出。

日常用例，为当前目录创建一个沙盒：

cd ~/code/my-project
clawk                      # 为当前目录启动沙盒并连接 claude
clawk run shell            # 进入同一沙盒中的 shell
clawk run codex            # 或使用其他代理：codex、opencode、shell
clawk down                 # 停止 VM（仓库和代理状态保留）
clawk attach               # 稍后回来 — 如果已停止则启动，重新连接 claude
clawk destroy              # 移除 VM（对话历史被保留）

常用选项：

clawk run claude -- --resume            # 向代理传递参数
clawk forward add my-project 3000       # 将客户机开发服务器暴露到 localhost:3000
clawk network allow my-project api.example.com

处理跨仓库的工单？一条命令即可创建一个沙盒，为每个仓库在新分支上生成 git worktree，之后 clawk pr 会为所有变更打开交叉链接的 PR：

cd ~/code/my-workspace     # 包含一个列出仓库的 clawk.mod 文件
clawk work INFRA-123       # 一个沙盒，每个仓库一个 worktree，已连接 claude
clawk pr INFRA-123         # 推送分支并为每个仓库打开一个 PR

完整的工单生命周期（状态、合并后的后续分支、变基）详见 docs/ticket-mode.md。

提示： 正在使用 Claude Code？运行 claude setup-token 然后 clawk auth set-token 一次，每个沙盒启动时便已登录，无需 /login，且并行沙盒之间不会出现登录冲突。详见 docs/claude-auth.md。

一条规则主宰持久性：VM 是一次性的；所有你不想丢失的东西都保存在宿主机上。

clawk down	clawk destroy
你的仓库（挂载的 worktree；提交、分支）	✅
代理状态（Claude/Codex 对话、记忆）	✅
VM 磁盘（apt 安装的包、缓存、$HOME）	❌（每次启动重新构建*）

• 两个例外：恢复 clawk snapshot 会将磁盘和内存精确恢复到挂起时的状态，而 Linux/firecracker 提供程序在销毁前会保留磁盘。每次启动都需要的工具应放入镜像（vm ( image … )）；每次启动的设置应放在 on up 钩子中。

代理状态按沙盒挂载在宿主机上：客户机的 ~/.claude/projects/、~/.claude/memory/（以及 codex 的 ~/.codex/）位于宿主机 ~/.clawk/namespaces/default/state/<name>/ 下，因此重建的沙盒通过 --resume 可恢复其旧对话。

默认完全自主（以及 --safe 退出选项）

运行器以其“外部沙盒”模式启动：claude 获得 --dangerously-skip-permissions，codex 获得 --dangerously-bypass-approvals-and-sandbox。在你的宿主机上这些标志是轻率的；但在这里它们正是重点：VM 边界和网络允许列表提供封控，代理可以全速工作而无需每步确认。代理只能影响你挂载和允许列表中的内容，不能更多（见 SECURITY.md）。

还是想要确认提示？在任何 attach 命令中添加 --safe（clawk --safe、clawk run claude --safe），运行器会在该会话中禁用 bypass 标志。

出站流量默认拒绝；每个沙盒有自己的允许列表。DNS 解析一切；对未列出的主机，TCP、UDP（包括 QUIC）和 ICMP echo 将被拒绝。常见的注册中心（npm、PyPI、crates.io、GitHub、Anthropic 等）已预允许，过滤器具有 DNS 感知能力，因此允许 example.com 后即使其 IP 轮换也能正常工作。

clawk network allow my-project api.stripe.com '*.internal.mycorp.com' 10.0.0.5
clawk network denials my-project     # 代理尝试但被拦截的请求
clawk forward add my-project 3000    # localhost:3000 → 客户机开发服务器

拒绝记录会按 客户机解析的主机名 记录，因此 clawk network denials 可读取为代理尝试访问的日志。可重用的命名策略（包括订阅外部黑名单如 oisd）以及将其分层组合的 use 链，请见 docs/networking.md。

无需配置文件；默认值合理。当项目需要更多自定义时，使用 clawk.mod 文件描述，采用类似 go.mod 的语法：

sandbox my-project (
    vm (
        cpu    4
        memory 8GiB
        image  golang:1.25          # 任意 OCI 镜像作为 rootfs
    )
    network ( allow api.example.com )
    forwards ( 3000 )
    env ( DATABASE_URL )            # 仅名称；值来自你的 shell
    on create ( "go mod download" )
    agent (
        instructions "请在运行破坏性命令前询问。"
    )
)

该块是一个 模板：在创建沙盒时快照，因此正在运行的沙盒绝不会意外变化。完整参考（共享、秘密文件、技能、代理记忆种子、多仓库工作区根目录）在 docs/configuration.md ；镜像和自定义客户机内核（包括用于嵌套虚拟化的 KVM 内核）在 docs/images.md。

clawk list                  # 所有沙盒
clawk status [<name>]       # 状态、转发、已拦截主机；--json 用于脚本
clawk up / down             # 启动/停止
clawk pause / resume        # 挂起/恢复运行中的 VM（保持在内存中）
clawk snapshot              # 保存到磁盘：RAM 释放，客户机完好；resume 恢复
clawk destroy               # 移除 VM；宿主机端状态保留

clawk snapshot 是沙盒的休眠机制：客户机内存与其磁盘一起保存，下次启动会精确恢复到当时状态。后台进程和开发服务器继续运行就像什么都没发生过，clawk attach 让你重新面对代理。完整的命令功能、运行器分发以及空闲管理机制（气球、准入控制、自动停止）在 docs/commands.md。

you ──▶ clawk CLI ──▶ per-sandbox daemon (detached; owns the VM)
                        ├─ gvproxy: in-process userspace TCP/IP stack —
                        │  the DNS-aware outbound filter the guest can't reconfigure
                        ├─ vsock bridge to the in-guest pty-agent (no sshd)
                        ├─ ssh-agent proxy, macOS (signing stays on the host)
                        └─ VM: Virtualization.framework (macOS) / firecracker (Linux)
                             ├─ clawk-init, PID 1 (no systemd, no cloud-init)
                             ├─ your repo, live-mounted over virtio-fs
                             └─ claude / codex / shell on a PTY

几点有意为之的选择，简要说明：

• rootfs 是普通的 OCI 镜像。 clawk 会拉取它（无需 Docker 守护进程），展平层，并直接写入 ext4 磁盘，无需 root 和 loop 设备。来自同一镜像的每个沙盒是写时复制克隆（APFS clonefile/FICLONE），所以每个沙盒的磁盘开销仅包含客户机写入的内容。
• 网络在客户机下方过滤。 VM 的整个 L3（网关、DHCP、DNS、NAT）是守护进程内的用户空间网络栈。每个出站连接和 DNS 回答都以此处的允许列表为准，即使客户机内的 root 也无法更改。无宿主机 iptables，无 sudo。
• 一条进路。 无 sshd，无 cloud-init：一个单一的 vsock 代理是进入客户机的唯一控制路径，每次 attach 类似容器 exec：一个全新进程，断开时拆除。

The full p

A coding agent is only useful when you let it actually do things: install packages, run the code it writes, start servers, use the network. On your own machine that leaves two bad options. You approve every command (and babysit a prompt every few seconds), or you run --dangerously-skip-permissions and hope nothing important is one rm -rf or one leaked token away.

clawk is a third option. cd into a repo, type clawk, and Claude Code (or Codex, or a shell) is working inside a disposable Linux VM (your code mounted in, root in the guest, no permission prompts) while your files, your keychain, and the rest of your machine stay out of reach. The agent gets its own machine instead of yours.

One command to a working agent; an attempt to send data to an unknown server, blocked by the network allow-list;clawk attach resumes the session later.

The boundary isn't a rule in a prompt the agent could be talked out of. It's a separate machine, and the only openings are the ones you mounted. From a shell inside a sandbox:

$ curl https://tracker.evil.example   # not on the allow-list: blocked
curl: (7) Failed to connect to tracker.evil.example port 443 after 2 ms: Connection refused

$ cat ~/.ssh/id_rsa                   # your keys never entered the VM
cat: /home/agent/.ssh/id_rsa: No such file or directory

$ git push                            # ...yet this works: ssh-agent is forwarded
Enumerating objects: 5, done.

To be honest about the limits, the allow-list blocks connections to unknown servers, not to ones you've allowed: github.com is pre-allowed and the forwarded ssh-agent can push, so treat anything the agent can read as something it could publish. The security model spells this out.

And if the agent wrecks the VM, run clawk destroy && clawk: a fresh VM, same repo, and --resume restores the conversation.

Important

Pre-1.0 and moving fast. Expect breaking changes between releases and the occasional rough edge; things can and will break. Please file issues; that feedback is shaping 1.0.

• Let the agent do anything. It runs in a disposable VM with a restricted network, so rm -rf, package installs, and untrusted code can't reach your host, your files, or anything you didn't explicitly share.
• Working in one command. cd into a repo and run clawk. No Dockerfile, devcontainer, or setup file. First boot builds a rootfs from your image; every boot after takes seconds.
• Break it without losing anything. Destroy and recreate freely; your code and the agent's conversations live on the host. Only the disposable VM disk is lost.
• A real Linux box, your toolchain. Any OCI image is the rootfs: a full OS with exactly the tools your project needs. No Docker daemon required.
• Secrets stay on your machine. Outbound traffic is allow-listed and your ssh-agent is forwarded, so git push works without keys entering the VM.
• A sandbox per project or ticket. Run several at once; multi-repo tickets get a git worktree per repo with coordinated PRs. Idle VMs automatically release memory and suspend to disk, so a forgotten sandbox costs (almost) nothing.

clawk is a general-purpose local environment for autonomous coding agents. The VM is the point: it's a whole machine the agent can own, not a process wrapped in policy on the one you're using.

• A separate kernel. The guest runs its own Linux kernel, so the host filesystem isn't hidden behind deny rules; it was never mounted.
• A conventional Linux environment. Standard kernel, standard userland, /dev/kvm-shaped expectations, so tools behave the way their docs say, without a syscall-filter surprise.
• Root in the guest. Install system packages, edit /etc, load a module, bind a privileged port. It's the agent's box to reconfigure.
• A disposable lifecycle. Cheap to break and quick to recreate; a wrecked VM is one clawk destroy && clawk away, with your repo and conversations untouched on the host.
• Stronger separation from the host. Isolation rests on the hypervisor boundary rather than on getting a process-sandbox policy exactly right.

That combination runs workloads a restricted process sandbox tends to fight you on:

• installing packages and native dependencies;
• running background services (databases, queues, dev servers);
• executing untrusted builds and tests at full speed;
• using system-level Linux tooling that expects a real machine;
• and, with a KVM-enabled guest kernel on supported hardware, container and Kubernetes dev workflows such as Docker or Kind running inside the sandbox. This is opt-in and hardware-gated; see Images for the exact requirements.

None of this is the product ; clawk is for local agent work in general. Docker and Kubernetes are just the sharpest example of "needs a real machine, not a sandboxed process."

Requires macOS 14+ on Apple silicon. (Linux is supported via firecracker and currently experimental; see VM providers for the gaps. This README is macOS-first.)

brew install clawkwork/tap/clawk

From source (contributors, or if you don't use Homebrew), needs Go 1.26+:

git clone https://github.com/clawkwork/clawk && cd clawk
make install

Either way there's no extra host tooling: no Docker, no qemu, no sudo. The hypervisor is Apple's Virtualization.framework, linked into the binary. First run probes for anything missing and offers to fix it.

Uninstall: clawk destroy your sandboxes, rm -rf ~/.clawk, then remove the binary with brew uninstall clawk (or delete it from $GOBIN for a source install). Nothing else was installed: there are no launchd jobs; the per-sandbox daemons are ordinary processes that exit with their VMs.

The everyday case, a sandbox for the directory you're in:

cd ~/code/my-project
clawk                      # boot a sandbox for this dir + attach claude
clawk run shell            # drop into a shell in the same sandbox
clawk run codex            # or another agent: codex, opencode, shell
clawk down                 # stop the VM (repo + agent state persist)
clawk attach               # come back later — boots if stopped, reattaches claude
clawk destroy              # remove the VM (conversation history is kept)

Common options:

clawk run claude -- --resume            # pass args through to the agent
clawk forward add my-project 3000       # expose a guest dev server on localhost:3000
clawk network allow my-project api.example.com

Working on a ticket that spans several repositories? One command creates a sandbox with a git worktree per repo on a fresh branch, and clawk pr later opens cross-linked PRs for whatever changed:

cd ~/code/my-workspace     # contains a clawk.mod listing the repos
clawk work INFRA-123       # one sandbox, a worktree per repo, claude attached
clawk pr INFRA-123         # push branches + open one PR per repo

The full ticket lifecycle (status, follow-up branches after merges, rebases) is in docs/ticket-mode.md.

Tip: using Claude Code? Run claude setup-token then clawk auth set-token once, and every sandbox comes up already signed in, with no /login and no login conflicts between parallel sandboxes. See docs/claude-auth.md.

One rule governs persistence: the VM is disposable; everything you'd miss lives on the host.

| clawk down | clawk destroy
---|---|---
Your repo (mounted worktree; commits, branches) | ✅ | ✅
Agent state (Claude/Codex conversations, memory) | ✅ | ✅
The VM disk (apt installs, caches, $HOME) | ❌ (rebuilt fresh at every boot*) | ❌ (that's the point)

• Two exceptions: resuming a clawk snapshot restores the disk and memory exactly as suspended, and the Linux/firecracker provider keeps its disk until destroy. Tools every boot needs belong in the image (vm ( image … )); per-boot setup belongs in on up hooks.

Agent state is host-mounted per sandbox: the guest's ~/.claude/projects/ and ~/.claude/memory/ (and codex's ~/.codex/) live under ~/.clawk/namespaces/default/state/<name>/ on the host, so a recreated sandbox picks up its old conversations with --resume.

Full autonomy by default (and the --safe opt-out)

Runners launch in their "externally sandboxed" modes: claude gets --dangerously-skip-permissions, codex gets --dangerously-bypass-approvals-and-sandbox. On your own machine those flags would be reckless; here they are the point: the VM boundary and the network allow-list provide the containment, so the agent works at full speed without per-action prompts. The agent can only affect what you mounted and allow-listed, nothing more (see SECURITY.md).

Prefer the confirmation prompts anyway? Add --safe to any attach (clawk --safe, clawk run claude --safe) and the runner starts without its bypass flags for that session.

Outbound traffic is denied by default; each sandbox has its own allow-list. DNS resolves everything; TCP, UDP (including QUIC), and ICMP echo to unlisted hosts are refused. Common registries (npm, PyPI, crates.io, GitHub, Anthropic, …) are pre-allowed, and the filter is DNS-aware, so allowing example.com keeps working as its IPs rotate.

clawk network allow my-project api.stripe.com '*.internal.mycorp.com' 10.0.0.5
clawk network denials my-project     # what the agent tried that got blocked
clawk forward add my-project 3000    # localhost:3000 → the guest's dev server

Denials are recorded by the hostname the guest resolved , so clawk network denials reads as a log of what the agent tried to reach. Reusable named policies (including subscribing to external blocklists like oisd) and the use chain that layers them are in docs/networking.md.

No config file is required; defaults are sensible. When a project needs more, a clawk.mod file describes it, in a go.mod-style syntax:

sandbox my-project (
    vm (
        cpu    4
        memory 8GiB
        image  golang:1.25          # any OCI image is the rootfs
    )
    network ( allow api.example.com )
    forwards ( 3000 )
    env ( DATABASE_URL )            # names only; values come from your shell
    on create ( "go mod download" )
    agent (
        instructions "Ask before running destructive commands."
    )
)

The block is a template : snapshotted when the sandbox is created, so a running sandbox never changes unexpectedly. The full reference (shares, secret files, skills, agent memory seeding, multi-repo workspace roots) is in docs/configuration.md ; images and custom guest kernels (including the KVM-enabled kernel used for nested virtualization) are in docs/images.md.

clawk list                  # all sandboxes
clawk status [<name>]       # state, forwards, blocked hosts; --json for scripts
clawk up / down             # boot / stop
clawk pause / resume        # suspend / resume the running VM in memory
clawk snapshot              # save to disk: RAM freed, guest intact; resume restores it
clawk destroy               # remove the VM; host-side state persists

clawk snapshot is hibernation for sandboxes: the guest's memory is saved beside its disk and the next boot restores the guest exactly where it was. Background processes and dev servers continue as if nothing happened, and clawk attach puts you back in front of the agent. The full command surface, runner dispatch, and the idle-management machinery (ballooning, admission control, auto-stop) are in docs/commands.md.

you ──▶ clawk CLI ──▶ per-sandbox daemon (detached; owns the VM)
                        ├─ gvproxy: in-process userspace TCP/IP stack —
                        │  the DNS-aware outbound filter the guest can't reconfigure
                        ├─ vsock bridge to the in-guest pty-agent (no sshd)
                        ├─ ssh-agent proxy, macOS (signing stays on the host)
                        └─ VM: Virtualization.framework (macOS) / firecracker (Linux)
                             ├─ clawk-init, PID 1 (no systemd, no cloud-init)
                             ├─ your repo, live-mounted over virtio-fs
                             └─ claude / codex / shell on a PTY

A few deliberate choices, in brief:

• The rootfs is an ordinary OCI image. clawk pulls it (no Docker daemon), flattens the layers, and writes an ext4 disk directly, with no root and no loop devices. Every sandbox from the same image is a copy-on-write clone (APFS clonefile / FICLONE), so per-sandbox disk cost is what the guest writes.
• The network is filtered below the guest. The VM's entire L3 (gateway, DHCP, DNS, NAT) is a userspace stack inside the daemon process. Every outbound connection and DNS answer consults the allow-list there, where even root inside the guest cannot change it. No host iptables, no sudo.
• One way in. No sshd, no cloud-init: a single vsock agent is the only control path into the guest, and each attach is container-exec-style: a fresh process, torn down on disconnect.

The full picture (the guest stack, both providers, the frame-level networking) is in ARCHITECTURE.md , and the reasoning behind each decision in DESIGN.md.

• Containers & devcontainers. They share your kernel and see your filesystem minus deny rules; a single kernel bug or a mistaken mount can expose the host. Devcontainer setups often bind-mount the host Docker socket to build images, handing the container control of the host daemon; clawk keeps Docker inside the VM instead. And there's no Dockerfile/devcontainer.json to write: any OCI image is the rootfs.
• OS-level agent sandboxes. Tools like Anthropic's sandbox-runtime apply process-level guardrails on your real machine: great for lightweight rules, but one policy mistake exposes everything (keychain included), and installs, background services, or a nested hypervisor are awkward to allow safely. clawk moves the whole workload onto a different machine.
• General-purpose VM managers (e.g. Lima). Lima gives you a Linux VM; clawk is a workflow on top of one: a VM per project with the repo mounted, an agent attached and authenticated, egress allow-listed by default and denials logged, agent conversations persisted across destroys, and a ticket mode that manages worktrees and PRs. (Under the hood both use Virtualization.framework.)
• Cloud sandboxes. Local-first: your code never leaves the machine, nothing is billed by the hour, and the worktree the agent edits is the one in your editor, live-mounted on macOS (the Linux provider currently bakes it in at create; see Roadmap). Cloud sandboxes fit fleets; clawk is for the machine on your desk.

Security model (and its limits)

Two boundaries do the work: the VM (the host filesystem is invisible except what you mount) and the outbound allow-list (enforced in userspace below the guest, for every protocol that can leave it). What clawk does not protect against:

• Whatever you mount or allow is exposed. Worktrees are writable, so an agent can commit bad code or push to any repo your forwarded ssh-agent can reach. Review what comes out of a sandbox like you'd review a stranger's PR.
• Secrets you push in are visible. files ( … ) and shares ( … ) contents, forwarded env vars, and the Claude token are the agent's to read (and, if a destination is allow-listed, to send there). Share the minimum.
• Hypervisor escapes. clawk relies on Virtualization.framework/KVM isolation; it does not add defenses beyond them.

If you find a way to break a boundary (guest-to-host escape, network-filter bypass, credential leakage), please report it privately via SECURITY.md.

What's the overhead? The first boot from an image pays a one-time rootfs build (pull → flatten → ext4). After that, disks are copy-on-write clones and the kernel direct-boots, with no firmware and no installer. Idle VMs release memory down to ~1 GiB, stop automatically after 30 idle minutes, and can be snapshotted to disk so they cost only storage.

Does it work on Intel Macs? Windows? No. macOS needs Apple silicon (macOS 14+). On Linux, the firecracker provider works but is experimental (see docs/commands.md). No Windows support.

Do I need Docker installed? No. clawk pulls OCI images and builds bootable disks itself. Docker images are the input format; the Docker engine is not involved. (Running a Docker daemon inside a sandbox is a separate, opt-in feature; see Images for the hardware and kernel requirements.)

Why "clawk"? The mark is a claw; clawkwork is a play on A Clockwork Orange. A VM you wind up, set loose, and can always reset.

Next up: running more sandboxes than your RAM can hold at once.

• Idle stops that snapshot. Manual suspend-to-disk shipped as clawk snapshot / clawk resume; next, the automatic idle stop uses it too, so dev servers survive the stop and a suspended sandbox costs only disk.
• A cap on running VMs. Instead of refusing a new VM when RAM is committed, suspend the least-recently-used sandbox to disk and start the new one.
• Firecracker parity. Live worktree propagation and host-file push on Linux.

Pre-1.0 and under active development, and evolving quickly: expect breaking changes between releases. The CLI surface changes least and internals most, but nothing is frozen until 1.0.

Issues and PRs are welcome. See CONTRIBUTING.md to build and test, ARCHITECTURE.md for how it's built, and DESIGN.md for where it's headed.

Apache License 2.0. clawk vendors two third-party components under their own licenses (gvisor-tap-vsock, Apache-2.0; an hcsshim ext4 writer, MIT); see NOTICE.