Disposable, network-restricted Linux VMs for AI coding agents.

clawk provides AI coding agents with isolated, disposable Linux VMs, addressing the security risks of running agents directly on developer machines. It enables agents to perform actions like package installation and network access within a controlled environment, safeguarding the host system. The target audience includes developers and researchers seeking secure, powerful local environments for autonomous coding tasks.

How It Works

The core approach utilizes a dedicated Linux VM per session, leveraging Apple's Virtualization.framework (macOS) or Firecracker (Linux). This hypervisor-level isolation provides a stronger boundary than containerization. Network egress is strictly controlled via a userspace, DNS-aware allow-list, preventing unauthorized outbound connections. Host files are mounted read-only or via specific worktrees, and agent state (conversations, code) persists on the host, making the VM disk disposable.

Quick Start & Requirements

• Install: macOS: brew install clawkwork/tap/clawk. Source: git clone https://github.com/clawkwork/clawk && cd clawk && make install (requires Go 1.26+).
• Prerequisites: macOS 14+ on Apple Silicon (primary). Linux support via Firecracker is experimental. No host Docker, qemu, or sudo needed.
• Setup: First boot builds rootfs; subsequent boots are seconds. Idle VMs suspend automatically.
• Docs: Available in the docs/ directory.

Highlighted Details

• Secure Agent Execution: Agents operate with full guest root privileges but are network-restricted and cannot access host secrets or arbitrary files.
• Effortless Setup: Launch a VM for the current directory with clawk. Supports any OCI image as rootfs, eliminating the need for Dockerfiles or devcontainers.
• Disposable & Persistent: VMs are ephemeral; agent conversations and code changes are persisted on the host and restored across destroy/recreate cycles.
• Multi-Repo Workflow: clawk work and clawk pr commands manage worktrees across multiple repositories for ticket-based development, automating PR creation.
• Network Control: Fine-grained, DNS-aware outbound traffic allow-listing enforced below the guest kernel. SSH agent forwarding allows Git operations without exposing host keys.

Maintenance & Community

The project is pre-1.0 and under active development, with frequent updates and potential breaking changes. Contributions via Issues and PRs are welcomed, with detailed architecture and design documentation available.

Licensing & Compatibility

Licensed under Apache License 2.0. It vendors components under MIT and Apache-2.0 licenses. Permissive for commercial use.

Limitations & Caveats

The project is pre-1.0, indicating potential instability and breaking changes. Primary support is for macOS on Apple Silicon; Linux support is experimental. The security model relies on hypervisor isolation and the network allow-list; mounted files, shared secrets, and forwarded environment variables are accessible to the agent. Hypervisor escapes are not defended beyond the underlying framework's capabilities. Live worktree propagation is currently macOS-only.