thundersnapd

Overview ¶

autorun.go provides process management for autorun commands configured on refs.

docker.go handles downloading and flattening Docker images into snaps.

frames_handlers.go provides HTTP handlers for the frame history/log API.

thundersnapd is a Tailscale tsnet-based SSH server that provides isolated container environments for each user session.

mcp.go implements the thundersnap MCP server, exposing the six sandbox-equivalent tools (bash, view, create_file, str_replace, list_frames, list_refs) on the daemon's HTTP listener at /v1/mcp.

This is a port of Aperture's chat/sandbox tool set (tool_bash.go, tool_view.go, tool_create_file.go, tool_str_replace.go) and the Tool→MCP adapter (proxy/mcp.go chatToolToMCPHandler), per sandbox-mcp-design.md. Per the project rule we do NOT import the aperture module: the self-contained command builders and the adapter are copied here.

The exec primitive is mcpexec.CollectFrames (thundersnap/mcpexec), the vshdproto-frame port of Aperture's CollectExec. The launcher below (runInFrame) is the daemon-specific glue: it resolves a frame, prepares its rootfs, dials the host vshd, sends the VMX one-shot header, and collects the result — the same path runContainerSession uses for SSH, minus the PTY.

metadata.go provides types and helpers for frame and snap metadata files. These are stored as .jsonc files alongside the btrfs subvolumes.

metrics.go wires the importable metrics package into the daemon's :7575 tsnet HTTP server, supplying the live session/VM counts from in-memory state.

NFS server implementation for thundersnapd. Provides NFSv3 server with maximal caching for high-speed file access.

policy.go implements the grant-based policy system for thundersnap. Policies can come from Tailscale CapMap grants or a local policy file.

Portmapper (rpcbind) implementation for thundersnapd. Provides a minimal portmapper that returns fixed ports for NFS and MOUNT services. Supports both TCP (with record marking) and UDP (without record marking).

refs_handlers.go provides HTTP handlers for the ref API.

snapqueue.go implements background, serialized snap indexing.

ts snap --quick / ts go :: capture a btrfs snapshot (instant, COW) and return at once; the slow part — walking the tree and hashing every file to derive the content-addressable snap ID — happens in a single daemon-wide background worker that drains captured snaps in FIFO order. Serializing indexing gives two properties the old synchronous code lacked:

1. No unbounded parallelism: concurrent ts snap calls capture quickly (the brief btrfs snapshot is serialized under snapQueue.mu) and then queue for indexing; the worker indexes them one at a time.
2. Rapid double-ts-snap chains incrementally: each snap records its base (the previous snap of that frame). When the worker reaches snap N, snap N-1 is already finalized, so snap N reuses N-1's chunk hashes for unchanged files instead of re-reading/re-hashing them.

See background-indexing.md for the full design.