gondolin-sandbox

Gondolin Sandbox (persistent VM)

While this skill is active, every Bash, Read, Write, and Edit tool call is bridged into a single long-running gondolin microVM scoped to the current Claude session. The host project directory is bind-mounted at /workspace inside the guest. State persists across calls — env vars, installed packages, background processes, and files anywhere in the guest rootfs survive between commands until SessionEnd.

Architecture

┌────────────── Claude Code (host) ──────────────┐      ┌── microVM ──┐
│  Bash ──► bash.sh ─┐                           │      │             │
│  Read ──► read.sh ─┤                           │      │  /workspace │
│  Write ─► write.sh ─┤ (PreToolUse hooks)       │      │  ◄──bind──► │
│  Edit ──► edit.sh ─┤   emit allow + rewrite    │      │             │
│                    ▼                           │      │             │
│           updatedInput.command|file_path       │      │             │
│                    │                           │      │             │
│        host runs the rewritten tool ──┐        │      │             │
│                                       ▼        │      │             │
│   PostToolUse: post.sh (shadow → VM) ──────────┼──► daemon (vm.js)  │
│                                                │   over Unix sock   │
│   SessionEnd: cleanup.sh ──────────────────────┼──► shutdown        │
└────────────────────────────────────────────────┘      └─────────────┘

How each tool is bridged

Bash → bash.sh

1. The first Bash call lazy-boots node vm.js daemon, which uses the gondolin SDK (VM.create) to start a microVM with /workspace bind-mounted to the project dir and listens on a Unix socket at ~/.cache/gondolin-skill/<session>/<scope>/vm.sock.
2. bash.sh base64-encodes the command and emits permissionDecision: "allow" with updatedInput.command rewritten to node vm.js exec --sock <sock> <BASE64>.
3. Claude Code's host Bash tool runs the wrapped command natively. vm.js exec connects to the daemon, sends the command, and streams stdout/stderr back as bytes arrive — so output appears in real time, not buffered to the end.

Read → read.sh

1. Resolves the agent-supplied path into VM_PATH (where it lives in the guest) and HOST_PATH (where the host Read tool will actually run).
2. For bind-mounted paths (under the project dir or /workspace/*): HOST_PATH is just the host equivalent — same bytes either way.
3. For VM-only paths (/tmp/foo, /etc/os-release, …): cats the file from inside the VM into a shadow file under ~/.cache/gondolin-skill/<session>/<scope>/shadow/<path> on the host, then redirects Read there.
4. Emits permissionDecision: "allow" with updatedInput.file_path set to HOST_PATH. Claude Code's host Read tool returns content exactly as it normally would.

Write → write.sh (+ post.sh)

1. Same path resolution as Read. Pre-creates dirname HOST_PATH for shadow targets so the host Write tool finds a writable directory.
2. Emits allow + updatedInput.file_path (preserving content via a JSON merge in emit_allow_file_path).
3. Host Write writes either the bind-mounted host file (no sync needed) or a shadow file.
4. post.sh (PostToolUse) inspects the final file_path; if it's under $SHADOW_ROOT, it pushes the bytes back into the VM at the corresponding VM path via vm_exec.

Edit → edit.sh (+ post.sh)

Same shape as Write — rewrite to shadow path, then sync back in PostToolUse. The host Edit tool does the actual exact-string replacement; we just give it the right file to mutate.

SessionEnd → cleanup.sh

Iterates every per-scope subdir under ~/.cache/gondolin-skill/<session>/, sends vm.js shutdown to each daemon's socket (graceful vm.close()), and removes the session dir.

Path resolution rules (gondolin_resolve_path)

Agent supplies	VM_PATH	HOST_PATH	Shadow?
/Users/.../microvm/foo	/workspace/foo	/Users/.../microvm/foo	no
/workspace/foo	/workspace/foo	/Users/.../microvm/foo	no
/tmp/foo (or any other absolute)	/tmp/foo	$SHADOW_ROOT/tmp/foo	yes
foo (relative)	foo	foo	no

$SHADOW_ROOT = ~/.cache/gondolin-skill/<session>/<scope>/shadow.

State semantics

• Persists for the whole Claude session: env vars, installed packages (apk add ...), files anywhere in the guest, background processes, working directory between calls.
• Synced via bind mount for paths under the project dir / /workspace: changes are immediately visible on both sides.
• Synced via shadow for VM-only paths: Read fetches VM → shadow; Write/Edit mutate shadow then PostToolUse pushes shadow → VM.
• Lost at SessionEnd: the VM is destroyed and a fresh one boots for the next session.

First-run setup

The first hook call in a session populates a runtime cache at ~/.cache/gondolin-skill/runtime/ by running:

npm install --silent --no-fund --no-audit @earendil-works/gondolin@latest

into that directory, then copies vm.js next to it so Node resolves @earendil-works/gondolin via the sibling node_modules. Subsequent sessions just spawn the daemon out of the cache.

vm.js is re-synced to the runtime cache on every hook call (it's a cheap cp), so edits or renames in the skill dir pick up on the next call without manual cleanup.

VM cold-boot (~few seconds + a first-ever ~200MB image download) is paid once per session, not per call. Subsequent calls just round-trip over the socket.

Caveats and limits

• Edit preflight: Claude Code's Edit tool checks "file exists on host" before PreToolUse hooks fire. That means Edit on /workspace/* or VM-only paths (/tmp/foo) fails with File does not exist — the hook never gets to redirect. Use the host-equivalent path (/Users/.../microvm/...) when editing bind-mounted files, and Bash (sed, awk, cat >) for VM-only files outside the bind mount.
• No TTY: interactive tools (vim, less, prompts) won't work — the guest is fed commands one at a time via the protocol, not via a pseudo-terminal.
• No host-shell features: each command runs as /bin/sh -lc <cmd> inside the guest. zsh-isms don't work.
• Single VM per session+scope: parallel Bash invocations to the same scope queue on the daemon (one command per connection at a time). Use __SCOPE=<name>__ <cmd> to spin up an isolated VM for a subagent.
• Requires Node ≥ 23.6 and QEMU on the host (brew install qemu on macOS).
• Project-scoped via .claude/settings.json — hooks fire for every agent in this project (orchestrator + subagents), regardless of whether this skill is loaded in context.

Debug bypasses

Bash command prefix	Effect
__HOST__ <cmd>	bash.sh rewrites to the unwrapped host command — inspect VM state, kill leaked QEMU.
__SCOPE=<name>__ <cmd>	Routes to a per-scope VM (separate daemon, separate /workspace mount).
__REWRITE_TEST__	Probe that PreToolUse allow + updatedInput actually rewrites the command.

Files

• _lib.sh — shared helpers: daemon bootstrap, vm_exec_*, gondolin_resolve_path / gondolin_unshadow, JSON emitters.
• bash.sh — PreToolUse for Bash (lazy-boot + rewrite-to-exec-client).
• read.sh — PreToolUse for Read (populate shadow + redirect).
• write.sh — PreToolUse for Write (redirect to shadow).
• edit.sh — PreToolUse for Edit (redirect to shadow).
• post.sh — PostToolUse for Write|Edit (sync shadow → VM).
• cleanup.sh — SessionEnd (per-scope graceful daemon shutdown).
• vm.js — Node program: daemon mode owns the VM and listens on the socket; exec mode is the thin streaming client; shutdown mode triggers vm.close().
• ~/.cache/gondolin-skill/<session>/<scope>/ — per-session, per-scope VM state (socket, daemon log, pid, shadow tree).
• ~/.cache/gondolin-skill/runtime/ — shared SDK install + copy of vm.js.
• ~/.cache/gondolin-skill/logs/rewrite.log — per-call Bash audit log.