Each term below has one meaning across the manual and names the section that defines it, and the index lists every figure by the claim it makes.
Every term is defined once, in the section the last column names, with the sources that section cites. The meanings below come from the help text, the schema, the kit specification, and the docs that the sources reference lists.
Glossary
| Term | Meaning in this manual | Defined in |
|---|---|---|
| Agent | One entry under agents, with a model, an instruction, toolsets, and optional sub-agents |
5.2 |
| Agent file | The YAML or HCL file docker-agent run loads, titled Docker Agent Configuration in the schema: agents, models, providers, toolsets, and the rules between them |
5.2 |
| Alloy | A model reference of two models with a comma between them, a,b, that the runtime alternates between in one conversation |
5.2 |
| Attestation | A signed statement attached to an artifact: SLSA provenance on a kit, or the DSSE publication statement on a shared agent | 4.3 and 6.4 |
| Audit record | One JSONL line the daemon writes for each decision under the auditkit directory, rotated by time, count, and size | 7.2 |
| Background agent | A sub-agent started by run_background_agent that runs while the parent continues |
sub_agents, transfer_task, and background_agents |
| Binding | A record in credentials.yaml of the credential mechanism and the domains approved for one service |
3.5 |
| Capability | A typed, versioned request a kit makes of the host, com.docker.sandbox/<name>@N, answered as granted, refused, or prompted |
4.2 |
| Cassette | The file --record writes with the model API interactions of a run, and --fake replays |
5.1 |
| Clone mode | The --clone workspace mode: the host repository is mounted read-only at /run/sandbox/source and the agent works on a private clone, whose commits return through the sandbox-<name> remote |
3.2 |
| Cloud sandbox | A sandbox run through sbx --cloud on Docker's compute, with no host workspace, a shape, and a TTL |
7.1 |
| Delegation | The transfer_task tool: the parent sends a task to a sub-agent, which runs in a sub-session and returns a result |
sub_agents, transfer_task, and background_agents |
| Environment file | sbxenv.yaml, which declares the agent, kits, workspace, secrets, ports, MCP servers, and host commands of one sandbox |
4.4 |
| Environment plan | The list of everything applying an environment file would set up, printed by sbx env plan and approved before create or run acts |
4.4 |
| Eval | A saved session that docker-agent eval replays in a container and scores |
5.6 |
| Flavor | A named YAML patch under flavors, applied with --flavor before the file is parsed |
5.2 |
| Forward proxy | The host proxy that HTTP and HTTPS requests from a sandbox pass through. It enforces policy and injects credentials | 3.4 |
| Gateway | The one MCP endpoint a sandbox sees, served on the host, through which every registered server is reached. The Toolkit gateway and the hosted gateway are separate things with the same name | 3.6 |
| Governance profile | A named profile from remote governance policies, assigned to a sandbox with --profile |
7.2 |
handoff |
The tool that handoffs: injects. It moves the whole conversation to another agent in the same session, and the previous agent leaves the loop |
sub_agents, transfer_task, and background_agents |
| Harness | An external coding CLI, claude-code, codex, pi, or opencode, that runs an agent instead of a model provider |
5.1 |
| Hook | A command, builtin, model, or evaluator that runs at one of the 33 lifecycle events of an agent | 5.5 |
| Kit | One OCI image whose manifest annotation vnd.docker.sandbox.kit.descriptor carries its declarations. For the sbx kit commands, a v1 or v2 artifact with a spec.yaml |
4.1 |
| Kit argument | A value for an argument a kit declares, given as --kit-arg name=value |
4.1 |
| Kit set | A kind: set descriptor that lists kits and is never published |
4.1 |
| Mixin | A kit of kind: mixin: an overlay on the filesystem of a workload, zero or more per composition |
4.1 |
| Model reference | provider/model, a name from models, auto, an alloy, or a first_available list |
5.2 |
| Models gateway | An address set with --models-gateway that model traffic routes through, with a Docker token |
R.6 |
| Permission rule | An allow, ask, or deny pattern on a tool name and its arguments, evaluated deny, then allow, then ask |
5.5 |
| Policy | A set of rules that controls what sandboxes can reach. Local rules apply to all sandboxes or to one | 3.3 |
| Policy scope | global, all sandboxes, or local, one sandbox named with --sandbox |
3.3 |
| Preset | allow-all, balanced, or deny-all, chosen once with sbx policy init |
3.3 |
| Provider | A model API docker-agent knows by id, such as anthropic or dmr, or an entry under providers with its own base URL |
5.2 |
| Proxy type | The PROXY column of sbx policy log: forward, forward-bypass, transparent, network, or browser-open |
3.4 |
| Proxy-managed | A credential whose real value stays on the host while the proxy swaps its sentinel into outbound requests. Also the literal sentinel value proxy-managed |
3.5 |
| Rule | One allow or deny entry of a policy, with a RULE_ID, a resource pattern, and a protocol |
3.3 |
| Safety mode | strict, balanced, restricted, or autonomous: what the runtime does with a tool call that no permission rule matched |
5.5 |
| Sandbox | A microVM with its own kernel and a private Docker Engine, in which the agent runs as a container. It has a name, a workspace, a template, and a lifecycle | 2.1 |
sandboxd |
The host daemon that owns every local sandbox, reached over a Unix socket | 2.4 |
| Secret | A value sbx secret set stores in the host keychain for one of 13 services, a custom host, or a registry. It never enters the sandbox |
3.5 |
| Sentinel | The placeholder value the agent sees in place of a secret, such as proxy-managed |
3.5 |
| Session | The record of one conversation in session.db: every message, tool call, sub-agent run, and cost |
5.6 |
| Shape | A billable cloud size, micro, small, medium, large, or xl, from 1 vCPU and 2048 MiB to 16 vCPU and 32768 MiB |
7.1 |
| Skills store | The shared directory of SKILL.md skills that sbx links into every sandbox, read-only by default |
4.5 |
| Static set | The MCP servers fixed at creation with --static-mcp, as opposed to servers attached later with sbx mcp load |
3.6 |
| Sub-agent | An agent listed in sub_agents that the parent delegates to with transfer_task |
sub_agents, transfer_task, and background_agents |
| Template | A container image a sandbox starts from: the default docker/sandbox-templates:<agent> image, a saved snapshot, or a loaded tar |
2.3 |
| Toolset | One entry under toolsets with a type from the 27 built-in types, which gives the agent a set of tools |
5.3 |
| Transparent proxy | The host proxy that intercepts TCP traffic other than HTTP and HTTPS. It enforces policy and injects nothing | 3.4 |
| TTL | The time-to-live of a cloud sandbox, 1 hour by default, under a 24 hour ceiling from creation | 7.1 |
| Workload | A kit of kind: workload: the root filesystem with entrypoint, cmd, env, user, and workdir, exactly one per composition |
4.1 |
| Workspace | The host directory a sandbox mounts at the same absolute path, read-write by default, with extra paths marked :ro |
2.1 |
Index of figures
Each number links to its figure, and the claim is the bold sentence that opens the caption.
| Fig. | The claim it makes |
|---|---|
| 0.1 | Each of the eight arrow styles marks one kind of exchange, and every label is a real command, rule, status, or event name from the capture. |
| 1.1 | sbx owns every layer from the daemon to the guest kernel, and docker-agent owns its binary, its files, and the loop inside the guest. |
| 1.2 | Both paths end with docker-agent in a microVM, but sbx run starts from a template image and docker-agent run --sandbox starts from your agent file. |
| 1.3 | docker-agent stages a kit, has sbx create the VM, and opens two hosts on the proxy, and the model call from inside then leaves through that proxy. |
| 2.1 | A sandbox is absent, running, stopped, or removed, and every sbx verb in this section moves it along exactly one edge. |
| 2.2 | A template moves from a stopped sandbox into the runtime image store, out as a tar, and into a new sandbox with --pull never -t. |
| 2.3 | Everything sandboxd owns on macOS sits under one Application Support directory, with the audit log under Logs and a symlink at ~/.sbx/run. |
| 3.1 | The agent sits on a private Docker Engine inside a guest kernel, and five doors cross the hypervisor line: mount, network, secret, MCP, and SSH agent. |
| 3.2 | The host repository enters the VM read-only at /run/sandbox/source, the agent commits to a private clone, and git-daemon serves that clone back as a host remote. |
| 3.3 | A matching deny ends the walk at once, an allow from any active scope admits the host, and a request that matches nothing is denied as implicit. |
| 3.4 | The first CONNECT is denied inside TLS by the proxy itself, one allow rule later the same CONNECT becomes a forward-bypass tunnel, and both leave a log row. |
| 3.5 | A host allow passes any request to github.com, body included, while a network-policy@2 entry denies one method on one host and leaves the rest open. |
| 3.6 | The sandbox only ever holds sbx-cs-<rand>, the forward proxy swaps it for the stored value on the bound host, and a direct connection gets no swap. |
| 3.7 | The host store holds m101-deepwiki once, each sandbox gets its own gateway at one URL, and a static set is fixed while load changes a dynamic one live. |
| 4.1 | The frontend copies the hello-kit descriptor into one manifest annotation, derives six more annotations from its fields, and records its own release in built-by. |
| 4.2 | One workload and two mixins merge into one grant set where allows union, deny wins, and a removed deny on the next version stops for approval. |
| 4.3 | A v2 kit is validated and packed on the host, signed and pushed with two referrers, verified from the registry, and consumed by create or kit add. |
| 4.4 | sbx env plan turns the file into margin-marked rows, approval on create records them, and a later plan prints only the rows that moved. |
| 5.1 | run loads the agent file, alternates model calls and tool calls in one loop, and writes the answer, the events, a session, and with --record a cassette. |
| 5.2 | files.yaml resolves local to the dmr provider and finds the endpoint itself, while dmr.yaml resolves qwen through providers.runner to a fixed URL. |
| 5.3 | Each toolsets entry becomes named tools in the model request: built-in types run in process, and mcp goes through a gateway, a child process, or a URL. |
| 5.4 | transfer_task sends writer only the task and returns its sentence to root, while the session move makes reviewer answer every later message. |
| 5.5 | The preempting hook allows every call only as advice, the patterns decide rm and echo, and the safety mode alone decides pwd. |
| 5.6 | The two replays of files.yaml match on all five turns, the guarded run differs at turn 0, and eval scores the same agent per tool call. |
| 6.1 | A session is created first and stored, and one POST to the agent path returns the whole turn as SSE frames from team_info to stream_stopped. |
| 6.2 | The same pong.yaml answers an editor through stdin and stdout and an MCP client through HTTP POSTs to port 8081, with different method names on each path. |
| 6.3 | The client reads the card, sends one blocking SendMessage that makes one model call, and gets back a completed task that GetTask returns again. |
| 6.4 | One share push stores files.yaml as an OCI manifest with four annotations, and share pull and run both read it back by the same reference. |
| 6.5 | Five callers reach the same runner through five base URLs, and every path after them is open to any client that reaches the port. |
| 6.6 | Compose pulls the model, injects two variables into printer, and runs the gateway with the API socket, which refuses a request without its bearer token. |
| 7.1 | sbx move copies the sandbox filesystem as one image and nothing else, so secrets, mounts, local rules, and processes stay behind while the destination starts a TTL clock. |
| 7.2 | One policy decision becomes one JSONL record on the developer machine, and only an enforced organization policy makes the daemon write it. |
| 7.3 | Each old name survived its successor for months, and Docker Desktop removed the two of them one week apart, on 2026-06-29 and 2026-07-06. |
| 7.4 | Eight claims were confirmed by a recorded file, five are reported without a test, and the community disputes one more. |
Original source
Sources: the definition paragraphs of sections 2.1 to 7.2 as research/plan.md plans them; research/sources/help-sbx.md (sbx create claude, sbx template, sbx kit, sbx policy, sbx policy init, sbx policy allow network, sbx policy log, sbx secret, sbx secret set-custom, sbx mcp ls, sbx run, sbx template load, sbx ttl, sbx policy profile, sbx daemon status, sbx skills); research/sources/help-docker-agent.md (run, eval, serve); research/sources/agent-schema.json (AgentConfig, HooksConfig, HarnessConfig, Toolset); research/sources/SPEC-v3-at-v3.0.0-m.8.md §1, §3.4, §7; research/sources/docs-sandboxes.md (pages architecture, configuration/credentials, governance/audit); research/sources/docs-docker-agent.md (pages concepts/models, concepts/agents, configuration/flavors, configuration/permissions, features/sessions, features/cli); the figure blocks of front.md and every file under sections/