Hardware-level sandbox for running coding agents inside QEMU microVMs. No containers, no disk images — each session boots a minimal NixOS guest on tmpfs with the host Nix store shared read-only.

Supported tools:

• Linux (x86_64 or aarch64)
• Nix with flakes enabled
• KVM access recommended (falls back to emulation without it)
• Valid credentials for your chosen tool (~/.claude, ~/.codex, or ~/.copilot)

# Run Claude
nix run github:braiins/llm-jail#claude

# Run Claude in dangerous mode
nix run github:braiins/llm-jail#claude -- --dangerous

# Run Codex
nix run github:braiins/llm-jail#codex

# Run GitHub Copilot CLI
nix run github:braiins/llm-jail#copilot

Pass tool arguments after --:

nix run github:braiins/llm-jail#claude -- -- -p "Refactor the auth module" --max-turns 5

llm-jail-{claude,codex,copilot} [options] [-- tool-args...]

Press Ctrl-a x to force-quit QEMU at any time.

Run Claude in dangerous mode for a fully autonomous task:

nix run .#claude -- --dangerous -- -p "Write hello to /workspace/hello.txt" --max-turns 3

Mount an extra directory and allocate more resources:

nix run .#claude -- --mount /tmp/data --mem 8192 --vcpu 4 -- -p "Process the dataset"

Enable git-over-SSH by mounting your SSH directory (read-only):

nix run .#claude -- --ro-mount ~/.ssh -- -p "Push the changes"

Use a nix dev shell inside the VM:

nix run .#claude -- --dev-env -- -p "Run the test suite"

Allow access to additional domains (e.g. for package installs or git cloning):

nix run .#claude -- --allow-domain github.com --allow-domain registry.npmjs.org

Disable network filtering entirely:

nix run .#claude -- --no-net-filter

Run nix build inside the VM with extra storage (root tmpfs is only 2G):

nix run .#claude -- --store-disk 20 -- -p "nix build and run the tests"

Filesystem. The guest boots on a tmpfs root. Only explicitly mounted directories are visible:

• The current working directory → /workspace (read-write)
• The tool config directory → /home/user/.claude, .codex, or .copilot (read-only overlay with writable persist dirs)
• ~/.gitconfig and the tool's JSON config are copied in (9p cannot mount single files)
• Host system and user packages → /host-sw, /host-user-sw (read-only, NixOS hosts only)
• Any directories added via --mount / --ro-mount

All other host paths are invisible to the guest. Changes outside mounted directories are lost when the VM shuts down.

On NixOS hosts, system packages (/run/current-system/sw) and user packages (/etc/profiles/per-user/$USER) are automatically mounted and added to PATH, so tools like jj, ripgrep, etc. are available without hardcoding them in the guest.

Processes. The agent runs inside a full QEMU virtual machine — separate kernel, separate PID namespace. There is no shared process space with the host.

Environment variables. Only these are forwarded to the guest:

• ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, CLAUDE_CODE_MAX_OUTPUT_TOKENS
• OPENAI_API_KEY, OPENAI_BASE_URL
• AWS_*

All other host environment variables are stripped.

Network. By default, outbound network access is restricted via DNS-based domain filtering and a port-level firewall:

• DNS resolution is limited to tool-specific API domains via a local dnsmasq instance
• Only HTTP/HTTPS traffic (ports 80/443) is allowed outbound; all other protocols are blocked by nftables
• Custom API endpoints (via ANTHROPIC_BASE_URL / OPENAI_BASE_URL) are automatically whitelisted
• Additional domains can be added with --allow-domain (subdomains are included automatically)
• Use --no-net-filter to disable all network restrictions

Default allowed domains per tool:

┌─ Host ──────────────────────────────────────┐
│  nix run .#claude                           │
│    ↓                                        │
│  writeShellApplication (mkRunner.nix)       │
│    • parses CLI args                        │
│    • writes env vars + tool args to tmpdir  │
│    • sets up 9p virtfs mounts               │
│    • optionally creates store disk image    │
│    • launches qemu-system-*                 │
└──────────────────┬──────────────────────────┘
                   │ QEMU (direct kernel boot)
┌─ Guest (NixOS) ──┴──────────────────────────┐
│  /nix/store ← overlay (9p lower + disk/tmpfs) │
│  /nix/var   ← bind from disk/tmpfs backing   │
│  /workspace ← 9p read-write                 │
│                                             │
│  systemd                                    │
│    → llmjail-mounts: mount 9p shares        │
│    → llmjail-net-filter: dnsmasq + nftables │
│    → llmjail-tool: exec claude/codex/copilot │
│                                             │
│  ExecStopPost: poweroff when tool exits     │
└─────────────────────────────────────────────┘

No persistent disk images are involved. The guest kernel and initrd are built by NixOS and passed to QEMU via -kernel / -initrd. The host Nix store is shared read-only over 9p and used directly as the lower layer of a /nix/store overlay. /nix/var is bind-mounted from the same backing volume so build artifacts (/nix/var/nix/builds/) land on disk rather than the root tmpfs. When --store-disk is used, a sparse ext4 image backs both; otherwise a tmpfs is used. The image is cleaned up automatically when the VM exits.

1. Add a guest module under guests/ (import common.nix, set llmjail.toolBinary and llmjail.dangerousFlag).
2. Add an entry to tools.nix pointing at the new module.
3. nix run .#your-tool — the flake generates a runner automatically.

This project is licensed under the MIT License.