Core concepts

Sandbox boundary

A sandbox is the manager-owned lifecycle record plus its Docker container, in-container daemon, runtime state, workspace root, and endpoints. Management operations create and destroy this boundary; runtime and observability requests name its sandbox ID.

The gateway accepts authenticated RPC from CLI, MCP, and console clients. It handles system-scoped management and forwards sandbox-scoped requests to the matching daemon.

Workspace sessions

A workspace session is a writable, isolated projection of a pinned LayerStack history. Its private upper directory records mutations while its lease keeps the lower-layer chain stable. Passing --workspace-session-id makes command and file operations target an existing session.

Omitting that ID from exec_command creates an automatic session with publish_then_destroy finalization. Explicit lifecycle operations are internal coordination surfaces and are intentionally not listed as public CLI or MCP tools.

Command sessions

A command session is narrower than a workspace session. It identifies one still-running process and its stable transcript. exec_command returns a command_session_id when work outlives the initial output wait; use it with read_command_lines or write_command_stdin.

Terminal state belongs to the command. Filesystem publication belongs to the containing workspace session, so a finished process and a published change are related but distinct events.

Snapshots and layers

With no workspace-session ID, file reads project the latest published snapshot. Writes and edits without a session publish one layer attributed to operation:<request_id>. Session capture instead attributes the layer to the workspace session.

LayerStack stores immutable base, published, and squashed layers in newest-first order. Leases pin live histories; squash replaces eligible runs with equivalent flattened layers and remounts live sessions onto the compact chain. See the LayerStack chapter for the storage model.

Publication and isolation

Commands run inside namespace and mount boundaries. Writes stay private until capture, and publication adds one resolved layer or rejects the change set. This avoids a last-writer-wins merge over concurrent work.

Network egress, reserved paths, mount masking, and shell execution are runtime capabilities rather than extra public operations. The namespace runtime and workspace coordination chapters explain those boundaries in depth.