Katsuobushi Sandbox

Checked: 2026-07-14

Summary

Katsuobushi Sandbox is a Nix library that boots a hermetic NixOS development VM through microvm.nix and QEMU. It is designed to run Claude Code with a dedicated guest kernel, a project clone, a writable Nix store overlay, default-deny outbound networking, and a local Git branch as the work artifact.

It can be used interactively over SSH or driven as a multi-turn quasi-subagent through an experimental host-to-guest channel.

Problem

Coding agents need a useful development toolchain and project context without gaining access to the host, sibling projects, or open internet. Rebuilding a complete toolchain inside every VM is slow. Katsuobushi combines VM isolation with declarative Nix configuration and read-only reuse of the host Nix store.

How It Works

• A Nix flake calls katsuobushi.lib.sandbox with the project, packages, allowed origins, secrets, resources, and optional context.
• QEMU boots a real NixOS microVM using KVM.
• The project is cloned into a per-instance workspace. Extra repositories can be copied in as pinned references.
• The host /nix/store is mounted read-only. A writable overlay and optional snapshot of the host Nix database let the guest reuse already-built Linux packages without downloading them again.
• The agent commits to sandbox/<instance> and pushes to a per-instance local bare Git mirror. sandbox fetch retrieves that branch into the host repository.
• Interactive mode opens SSH. Agent mode keeps Claude Code in a detached tmux session and accepts prompts over a private vsock channel.
• Named instances keep branch and disk-backed caches after stopping; ephemeral instances are removed.

Security Boundary

• The primary boundary is a QEMU VM with a dedicated guest kernel, not a container sharing the host kernel.
• The agent runs without root or sudo.
• DNS is disabled. Outbound traffic must pass through a dedicated HTTPS proxy and a hostname allowlist enforced by nftables below the agent’s privilege level.
• The project is a guest clone, not a writable bind mount of the host working tree.
• Host-to-guest prompts use vsock, bypassing IP networking. The controller accepts only the host context identifier, and the channel carries control and status rather than code.
• Host Nix store contents are readable inside the guest but mounted read-only. Users must not assume everything in the store is secret-safe.
• Optional GPU acceleration adds a host attack surface through virglrenderer inside QEMU. The documented software-rendering mode avoids exposing a virtual GPU parser.
• A VM escape, QEMU vulnerability, unsafe extra NixOS module, overly broad context mapping, or user-expanded allowlist can weaken the boundary.

Platforms and Agents

• Host: Linux with KVM, /dev/kvm, and Nix flakes.
• Agent mode additionally needs /dev/vhost-vsock and the vhost_vsock kernel module.
• Guest: NixOS Linux.
• Agent: currently designed around Claude Code. The library lets users put another harness on PATH, but the channel controller and subscription-token workflow are Claude-specific.
• macOS host support is a future plan, not current functionality.
• Optional headless Sway graphics supports browsers and Wayland applications.

Setup

1. Install Nix with flakes on a Linux KVM host.
2. Initialize from the repository’s sandbox flake template or call the library from an existing flake.
3. Set a project identifier, packages, CPU, memory, storage, approved origins, and required secrets.
4. Run the built-in status preflight to verify secrets and vsock.
5. Start interactively, or launch agent mode with an initial prompt.
6. Continue the same live Claude conversation with sandbox prompt; use sandbox attach to watch it.
7. Fetch the pushed branch, then stop or remove the VM.

The configuration is declarative but assumes comfort with Nix, NixOS modules, Git, QEMU, and Linux host devices.

Network and Credentials

• Outbound access is default-deny and limited to HTTPS destinations in an exact hostname allowlist. No implicit subdomain wildcard is added.
• The baseline permits selected Anthropic, Nix cache, and GitHub flake endpoints; projects add only what they need.
• This is destination filtering, not HTTP payload inspection. An allowed service can still receive source code or credentials visible to the agent.
• Secrets are read from a named host environment variable or file at launch.
• QEMU fw_cfg delivers secrets into a RAM-backed guest file; they are not written to the Nix store, command arguments, or guest disk.
• Claude’s subscription OAuth token is a live credential available to the agent because the harness needs it. The sandbox limits destinations but does not make the token unreadable to the guest.
• The Git mirror is local, so work returns without granting the guest direct write access to the host checkout.

Strengths

• Dedicated-kernel local VM boundary with an unprivileged agent.
• Declarative and reproducible toolchain, network, resource, context, and secret configuration.
• Default-deny networking with a small explicit allowlist.
• Host Nix store reuse can avoid repeated downloads and builds while remaining read-only.
• Git branch handoff avoids shared-worktree collisions and direct host edits.
• Multi-turn host control, pause/restart workflow, status reporting, attach, and optional screenshots.
• Disk-backed sparse caches allow realistic builds without tying writable space to guest RAM.

Limits and Risks

• Linux, KVM, Nix, and currently Claude-focused; not a general cross-platform agent tool.
• Agent mode depends on Anthropic’s experimental Channels feature. A vendor change can break it; interactive mode is less exposed.
• The README calls the channel workflow a research preview and the author called the project a hacked-together non-product on HN.
• HTTPS hostname allowlisting does not inspect data sent to an allowed endpoint.
• The agent receives a usable Claude credential and can use it within permitted routes.
• A stopped VM loses live conversation memory; its pushed branch persists, so the next prompt must be self-contained.
• Named-instance caches and disks consume host storage until removed.
• Importing the host Nix database is Linux-store-specific and does not directly translate to macOS.
• Optional hardware graphics weakens host integrity by adding a virtual GPU parser with a history of escape vulnerabilities.
• The README warns that exactly 2048 MiB of guest memory can hang QEMU in this setup.

Activity and Maturity

• Repository created 2026-03-19 and active through 2026-07-10.
• The sandbox path had active feature, fix, and documentation commits through 2026-07-03.
• GitHub showed 2 stars, no forks, no published release, and no repository license detected.
• The project is a library inside a broader personal Nix flake repository, not a standalone supported product.
• The detailed documentation and explicit security caveats show serious implementation work, but adoption, compatibility guarantees, and independent review are minimal.

Best Fit

• Nix-flake users on Linux who want strong local isolation for Claude Code.
• A human or orchestrating agent that wants a controllable multi-turn Claude subagent and Git branch handoff.
• Projects with large Nix toolchains that benefit from reusing the host store offline.
• Agent work that needs optional browser rendering inside a VM.

It is a poor fit for non-Nix teams, macOS or Windows hosts, turnkey support expectations, or agents other than Claude that need the channel workflow.

Comparison Facts

Fact	Katsuobushi Sandbox	Clawk
Host	Linux with KVM and Nix	macOS and Linux VM paths
Guest	Declarative NixOS microVM	Disposable Linux VM
Agent	Claude-focused channels; custom package possible	Agent-oriented local VM workflow
Project flow	Clone and local bare Git branch	Project VM workflow and forwarding
Network	Default-deny HTTPS hostname allowlist; DNS disabled	Userspace domain allowlist before dialing
Secrets	QEMU fw_cfg to RAM-backed file	VM credential workflow; no equivalent delivery documented in HN
Toolchain	Nix store overlay and database reuse	Conventional guest provisioning
Multi-turn control	Experimental Claude Channels over vsock	Direct agent use inside managed VM
Maturity	Research library, no release	Young standalone tool

Katsuobushi favors reproducibility and orchestration for Nix users. Clawk favors a broader, simpler standalone local workflow.

Hacker News Context

Author cdata presented the sandbox in the Clawk thread as a Claude-only microvm.nix alternative. The comment highlighted multi-turn Channels control, declarative copied context and network origins, the host Nix store overlay, local Git synchronization, status commands, and quick VM startup.

In reply to a hosted NixOS sandbox vendor, the author called Katsuobushi a hacked-together non-product with many of the same virtues. Another commenter wanted external token injection and stronger network control; Katsuobushi’s current README documents RAM-only token injection, but its proxy restricts destinations rather than keeping the token outside the guest or inspecting payloads.

Unknowns

• Independent security review, escape testing, or production incident history.
• License terms; GitHub did not report a repository license.
• Whether non-Claude agents work cleanly beyond interactive use.
• Measured startup time on current hardware; the HN claim of a few seconds differs from current README guidance that restarting a paused agent can take roughly 30–60 seconds.
• Long-term compatibility with Claude Channels and subscription authentication.

Sources

• Katsuobushi Sandbox README
• Katsuobushi Sandbox implementation
• Katsuobushi repository
• microvm.nix
• HN: Clawk discussion
• HN: Katsuobushi comment