Berry Wiki

Clawk

Properties2
tagsai, sandboxing
aliasesClawk

9 min read

Clawk

Project Summary

Clawk gives an AI coding agent a disposable, network-restricted Linux virtual machine (VM) on a developer’s computer. The agent can work with few prompts and have root access inside the guest machine without gaining general access to the host computer.

  • Repository: clawkwork/clawk
  • License: Apache-2.0
  • Implementation: Go
  • Status checked: 2026-07-14

Problem Solved

Coding agents are most useful when they can install packages, run services, execute tests, and use the network. Doing that directly on a laptop creates a poor choice: approve each action or grant broad access to the host.

Clawk creates a third option. It gives the agent its own machine-like workspace while keeping the rest of the laptop outside that workspace.

How It Works

  • One VM per sandbox: A small background process owns each VM.
  • Linux guest: macOS uses Apple’s Virtualization.framework. Experimental Linux support uses Firecracker.
  • Image-based root disk: Any OCI container image can become the VM’s Linux filesystem. Docker itself is not required.
  • Live project mount: On macOS, the selected repository or worktree is mounted into the VM with virtio-fs.
  • Agent terminal: Claude Code, Codex, OpenCode, or a shell runs inside the guest on a pseudo-terminal.
  • Host-kept state: Repository changes and agent conversation state live on the host and can survive VM destruction.
  • Ticket workflow: One sandbox can contain worktrees from several repositories, then create linked pull requests.

The design is like giving a contractor a separate workshop. They can rearrange or damage the workshop, but only the materials deliberately carried inside are exposed.

Security And Isolation Boundary

Clawk relies on two main boundaries:

  • Hypervisor boundary: The guest has a separate Linux kernel. Host files are invisible unless explicitly mounted.
  • Network allow-list: Outbound traffic is blocked unless its destination is allowed. Filtering runs below the guest, so root inside the VM cannot change it.

The guest does not run an SSH server. A vsock bridge is the single control path into it.

This is stronger host separation than a normal container or process sandbox, but it is not perfect:

  • Mounted data is exposed: The agent can change anything mounted writable.
  • Allowed destinations are trusted paths: An agent can send readable data to any allowed service.
  • Forwarded Git authority is powerful: The SSH agent can let the guest push to repositories the host identity can access.
  • VM escapes remain possible: Clawk depends on the security of Virtualization.framework or KVM/Firecracker and adds no extra protection against a hypervisor flaw.
  • Output still needs review: A sandbox can contain damage, but it cannot prove that the code produced is safe or correct.

Supported Platforms And Agents

  • macOS: Primary path; requires macOS 14 or later on Apple silicon.
  • Linux: Firecracker provider is experimental and does not yet match all macOS behavior.
  • Intel Mac: Not supported.
  • Windows: Not supported.
  • Built-in runners: Claude Code, Codex, OpenCode, and shell.
  • Other tools: Likely possible through the shell or custom configuration, but the official docs do not claim a complete agent compatibility list.

Workflow And Setup

Basic macOS installation and use:

brew install clawkwork/tap/clawk
cd path/to/project
clawk

Useful lifecycle actions include:

  • clawk run codex — run Codex in the project sandbox.
  • clawk down — stop the VM while preserving host-side project and agent state.
  • clawk attach — return to the sandbox and Claude session.
  • clawk destroy — delete the VM while preserving mounted repository and conversation state.
  • clawk snapshot — save VM memory and disk state for later resumption.
  • clawk forward add <sandbox> <port> — expose a guest service on host localhost.
  • clawk network allow <sandbox> <host> — add a network destination.

No project configuration is required for the default flow. A clawk.mod file can declare CPU, memory, image, ports, network access, passed environment-variable names, setup hooks, mounts, and agent instructions.

Clawk normally starts supported agents with their permission checks bypassed because the VM and network policy are intended to be the boundary. --safe keeps the agent’s own confirmation prompts enabled.

Network And Credential Handling

  • Default network policy: Outbound connections are denied unless allowed.
  • Pre-allowed services: Common code hosts, package registries, and model providers are included by default. This weakens strict data-loss prevention because readable data could be sent to those services.
  • Protocol coverage: The project says TCP, UDP, QUIC, and ICMP echo are filtered. DNS can resolve any name, but a connection to an unlisted target is refused.
  • DNS-aware rules: Hostname rules continue to work when addresses change.
  • Denial log: Users can inspect attempted blocked destinations.
  • SSH keys: The macOS SSH agent is proxied. Signing happens on the host, so private key files do not enter the guest.
  • Claude authentication: A stored Claude setup token can be supplied to sandboxes.
  • Explicit secrets: Passed environment values, shared files, and tokens become readable inside the guest. The project advises sharing the minimum.
  • Unknown: The public docs do not establish independent security review, formal verification, or a security audit.

Strengths

  • Strong local boundary: Separate-kernel isolation keeps most host data outside the agent’s view.
  • Low-friction autonomy: Agents can install system packages and run background services without repeated approvals.
  • Local-first: Source code does not need to be uploaded to a sandbox provider.
  • Useful network control: Per-sandbox allow-lists and denial logs address data exfiltration as well as accidental host damage.
  • Real Linux behavior: Root, databases, Docker, and Kubernetes-style development can work more naturally than inside a restricted process.
  • Disposable recovery: Destroying a broken VM does not discard the host worktree or saved agent conversation.
  • Multi-repository support: Ticket mode coordinates worktrees and pull requests across repositories.

Limits And Risks

  • Pre-1.0: Breaking changes and rough edges are explicitly expected.
  • New project: It was created on 2026-07-06, so its operational track record is short.
  • macOS-first: Linux is experimental; Windows and Intel Macs are unsupported.
  • Resource cost: Each active sandbox is a VM. Idle memory can fall to about 1 GiB, but many active sandboxes can still exhaust memory or disk.
  • Broad allowed services: GitHub, model APIs, and registries are useful but can also become paths for leaking mounted data.
  • Credential reach: Forwarded SSH signing can push malicious or unwanted changes wherever the host identity is authorized.
  • Writable worktree: Isolation protects the rest of the host, not the mounted project.
  • Linux privilege difference: The author stated that Firecracker’s TAP network device requires sudo; macOS network filtering does not require host root.
  • Trust remains: Users must trust a young VM manager, its vendored network component, its downloaded guest assets, and the host hypervisor.

Project Activity And Current Maturity

Checked 2026-07-14:

  • Latest release: v0.2.0, published 2026-07-13.
  • Repository age: Created 2026-07-06.
  • Latest main commit checked: 9c35a76c0b37, dated 2026-07-13.
  • Visible interest: 425 GitHub stars and 9 forks at check time.
  • Declared maturity: Pre-1.0 and under active development.
  • Assessment: An active early-stage tool with unusually detailed design and security documentation, but too new to treat as proven infrastructure.

Best Fit

Clawk is best for an Apple-silicon Mac developer who:

  • runs Claude Code or Codex with broad command access;
  • needs package installs, databases, containers, or Linux system tools;
  • wants local source code and agent state;
  • wants stronger separation than an agent’s built-in process sandbox;
  • accepts reviewing all changes and managing explicit network access.

It is a weaker fit for Windows or Intel Mac users, Linux users needing stable production behavior, low-memory machines, or teams requiring audited controls and centralized fleet management.

Comparison-Relevant Facts

  • Versus Docker/devcontainers: Clawk uses a separate kernel and avoids mounting the host Docker socket. It requires less project setup but costs more resources than a container.
  • Versus Bubblewrap, Landlock, or Firejail: Clawk gives stronger kernel separation and a whole Linux machine; process sandboxes start faster and reuse the host environment.
  • Versus Lima or Incus: Clawk adds agent runners, host-kept conversation state, default network restrictions, denial logs, project lifecycle, and multi-repository ticket handling.
  • Versus cloud sandboxes: Clawk is local and has no hourly service charge. Cloud tools better fit centralized fleets and keep the workload away from the user’s home or office network.
  • Versus Apple Container: Both build on Virtualization.framework and use one VM per container on macOS. The OP said Clawk moved to raw Virtualization.framework to implement network filtering.
  • Distinctive combination: Disposable local VM, destination allow-list, agent authentication, persistent conversations, and cross-repository worktree/PR workflow in one command-line tool.

HN Comment Context

The Hacker News discussion centered on whether a full VM is worth its cost and whether Clawk is meaningfully different from many existing agent sandboxes.

The OP, celrenheit, clarified:

  • Why a VM: Their tests start Docker containers, and their Kubernetes work needs a real cluster. A separate user or ordinary container still shares the host kernel and makes nested Docker/Kubernetes awkward.
  • How filtering works: On macOS, gvproxy ends guest connections and re-dials them as host sockets. A small hook checks TCP, UDP, and ICMP destinations against the allow-list before dialing.
  • Linux difference: Firecracker uses a TAP device that requires sudo, although the same userspace allow-list performs filtering.
  • Why one backend: Earlier multi-backend work made consistent network filtering difficult. Clawk focuses on one network-restricted VM path the author controls.
  • Why local-first: Company policy may forbid source code on a third-party remote VM. Remote environments are still on the roadmap, and clawk.mod was designed with that future in mind.
  • Platform reality: macOS is the tested, out-of-box path; Linux worked for the author but was not their daily environment.
  • Agent location: Claude Code and Codex run inside the Linux guest, not as host macOS processes.
  • Apple Container decision: Early versions used Apple Container. Raw Virtualization.framework was retained to support network filtering.

Other commenters raised useful comparison points:

  • Containers and process sandboxes are much lighter, but share the host kernel.
  • A VM beside the laptop may still be less separated from the local network than a cloud sandbox.
  • Disk and memory use can become a practical limit when running many agents.
  • Similar projects use Firecracker, Bubblewrap, Landlock, Incus, Nix microVMs, Kubernetes, LXC/eBPF, or policy-aware proxies.
  • Several commenters questioned whether another young sandbox should be trusted without more testing. That concern is material because Clawk’s security promise is its main value.

Sources

Graph View