gondolin-sandbox

gondolin-sandbox

A Claude Code plugin that sandboxes every Bash, Read, Write, and Edit tool call inside a persistent gondolin microVM, scoped to a single Claude session.

• Bash runs inside the VM. Output streams back in real time.
• Read, Write, Edit act on the same filesystem the VM sees — either directly via a bind mount, or through host-side shadow files synced into the VM after each write.
• State (env vars, installed packages, background processes, files anywhere in the guest rootfs) persists across calls. The VM is destroyed at SessionEnd.

Why

Running apt install … (or apk add …) shouldn't pollute your dev machine. Letting an agent edit /etc/... shouldn't actually edit your host's /etc/.... With this plugin, the agent's "filesystem" is the VM's filesystem — your host stays clean.

How it works

The plugin ships PreToolUse hooks for Bash/Read/Write/Edit, a PostToolUse hook for Write/Edit, and a SessionEnd cleanup hook. All hooks share a single shell library and a Node helper:

┌────────────── 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        │
└────────────────────────────────────────────────┘      └─────────────┘

The first hook in a session lazy-boots node vm.js daemon, which uses the gondolin SDK to start a microVM with the project dir bind-mounted at /workspace. Subsequent hook calls reuse the same daemon over a Unix socket.

Full architecture and edge cases: plugins/gondolin-sandbox/skills/gondolin-sandbox/SKILL.md.

Requirements

• macOS (Apple Silicon tested) or Linux
• Node ≥ 23.6
• QEMU — brew install qemu on macOS
• Claude Code with hooks support

Layout

.claude-plugin/
└── marketplace.json                   # exposes this repo as a plugin marketplace
plugins/gondolin-sandbox/
├── .claude-plugin/plugin.json         # plugin manifest
├── hooks/hooks.json                   # hook bindings (used when installed as a plugin)
└── skills/gondolin-sandbox/
    ├── SKILL.md                       # in-depth architecture doc
    ├── _lib.sh                        # shared bootstrap, vm_exec, path resolution, JSON emitters
    ├── bash.sh                        # PreToolUse Bash
    ├── read.sh                        # PreToolUse Read
    ├── write.sh                       # PreToolUse Write
    ├── edit.sh                        # PreToolUse Edit
    ├── post.sh                        # PostToolUse Write|Edit (shadow → VM sync)
    ├── cleanup.sh                     # SessionEnd (graceful per-scope shutdown)
    └── vm.js                          # Node program (daemon | exec client | shutdown)

.claude/
└── settings.json                      # this repo dogfoods the plugin by pointing
                                       # hooks at the plugin scripts directly.

Install

Inside Claude Code, in any project where you want the sandbox:

/plugin marketplace add jedi4ever/cc-gondolin-sandbox
/plugin install gondolin-sandbox@gondolin

Or, from a shell:

claude plugin marketplace add jedi4ever/cc-gondolin-sandbox
claude plugin install gondolin-sandbox@gondolin --scope project   # or --scope user

The first command registers this repo as a plugin marketplace (named gondolin from .claude-plugin/marketplace.json); the second installs the gondolin-sandbox plugin from it. Reload the session and every Bash/Read/Write/Edit tool call routes through the microVM.

To install from a local clone instead of GitHub:

/plugin marketplace add /path/to/microvm
/plugin install gondolin-sandbox@gondolin --project   # or --user

Updating

claude plugin marketplace update

Using it in this repo

.claude/settings.json already wires the hooks to the plugin scripts via ${CLAUDE_PROJECT_DIR}, so opening this repo with Claude Code activates the sandbox automatically — no /plugin install needed.

Path semantics (Read/Write/Edit)