Sandbox

Sandbox

A Sandbox is one running agent.

One installed agent, on one machine, governed by one Compiled Policy, executing the Provider recipe of one Runtime.

The unit of multi-tenancy. Each Sandbox gets its own identity, its own audit stream, its own capability tokens. Cross-sandbox isolation is enforced at every layer.

At a glance

Takes	a Compiled Policy (rules) + a Runtime (recipe of Providers)
Does	governed execution of the agent — every call passes through TapPass enforcement
Outputs	signed audit events + per-call denial reasons + the agent's actual work
Lifecycle	tappass-host start → runs → tappass-host stop (or tappass sandbox revoke)

What it is, concretely

When a host owner runs tappass-host start <name>, a Sandbox is what gets created.

It binds together:

• An identity (sandbox_id, plus the org/project it belongs to)
• A Compiled Policy (the rules — copied to a read-only mount inside the sandbox)
• A Runtime (the recipe of which Provider handles which ring)
• An isolated process environment (network namespace, user namespace, mount namespace, Landlock rules — applied by the kernel-ring Provider)

Multiple Sandboxes can co-exist on one host. Different Sandboxes can use different Runtimes from the same Policy — that's how a single Policy governs every ecosystem the customer uses.

A Sandbox cannot migrate between hosts. To move it, you re-enroll it on the new host.

What it's made of

Sandbox
├── Sandbox identity:    sandbox_id, sandbox_name, org_id, project_id
├── Sandbox-spec:        named template that produced it (e.g. "collibra-steward")
├── Runtime:             which provider recipe this sandbox runs under
│                        (e.g. "claude-code-laptop" = claude-code + nono + monty + anthropic-gateway + mcp-broker)
├── Compiled Policy (Keyring):  canonical signed IR (each provider in the runtime renders its own slice)
├── Mount points:        /var/run/tappass/<sandbox_id>/{keyring.json, agent-data/}
├── Process namespace:   network ns, user ns, mount ns, Landlock rules (when kernel-ring provider supports them)
└── Status:              pending_enrollment | active | revoked | offline

A sandbox lives on one host machine. Multiple sandboxes can co-exist on one host (different UIDs, different namespaces). A sandbox cannot migrate between hosts — re-enrollment is required for that.

Lifecycle

[create-spec]      Operator: tappass sandbox-spec create --name X --policy Y --layers all
                   → sandbox-spec saved (template, no instances yet)
   │
   ▼
[mint-bootstrap]   Operator: tappass sandbox-spec emit-bootstrap X --count N
                   → N single-use bootstrap URLs, 15-min TTL
   │
   ▼ (operator hands URL to host owner)
[enroll]           Host owner: tappass-host init <name> --enroll-url <url>
                   → Sandbox row created, status=pending_enrollment
                   → Host establishes mTLS to TapPass
                   → Bootstrap URL burned
   │
   ▼
[start]            Host owner: tappass-host start <name> --agent <pkg>
                   → Layer appliers run (kernel → codemode → harness → mcp → gateway)
                   → Keyring mounted RO into agent's namespace
                   → Privileges dropped; agent entrypoint exec'd
                   → status=active on first heartbeat
   │
   ▼
[run]              Agent makes calls; pipeline runs; audit emits.
                   On policy change → sync push → keyring re-applied (live).
   │
   ▼ (optional anytime)
[rotate]           Operator: tappass sandbox rotate <id> → new tokens issued via sync
   │
   ▼ (optional)
[revoke]           Operator: tappass sandbox revoke <id>
                   → Tokens revoked; next call returns 401 sandbox_revoked
                   → status=revoked
   │
   ▼
[stop]             Host owner: tappass-host stop <name>
                   → Process killed; namespaces torn down; keyring file deleted
                   → status=offline (sandbox row preserved for audit)

Engines that operate on Sandbox

Engine	What it does	Status
Sandbox-spec creator	Authors the named template	concept (within tappass-cli)
Bootstrap URL issuer	Mints single-use URLs from a sandbox-spec	concept (within tappass-cli)
Bootstrap consumer	Exchanges bootstrap → mTLS + keyring on the host	concept (within host-runtime-cli)
Layer appliers (5)	Materialize the keyring on the host at sandbox start	concept (q09-rings-and-cross-cutting/)
Sandbox revoker	Kills tokens; blocks future calls	concept (within tappass-cli)
Sandbox rotator	Forces token re-issuance without policy change	concept (within tappass-cli)
Heartbeat / liveness	Status updates from host → dashboard	concept (within tappass-host daemon)

Quick-starts (sandbox-specs)

A sandbox-spec is a named template that says which Policy applies and which Layers are enabled. Quick-start sandbox-specs ship for common agent shapes:

Sandbox-spec	Agent shape	Status
customer-support-emailer	gmail.send-driven support replies	planned
refund-processor	Stripe partial refunds with approval	planned
code-reviewer	GitHub PR comments via gh CLI	planned
data-engineer-agent	SQL against analytics DB	planned
internal-kb-assistant	RAG over internal docs	planned
collibra-steward	Catalog modifications (the demo agent)	concept
custom (always available)	Operator authors layer activation manually	n/a

A quick-start sandbox-spec selects layer activation, default capability scoping, and (often) a paired Policy template — so applying one is one click.

Surfaces

Persona	Surface	What you do
Operator	tappass sandbox-spec create / list / emit-bootstrap	author templates, mint bootstraps
Operator	tappass sandbox list / revoke / rotate / keyring	manage instances
Operator	Onboarding wizard	visual equivalent of CLI
Host owner	tappass-host init / start / stop / status / inspect / shell / logs	local sandbox lifecycle
Operator (visual)	Dashboard sandbox list	status per sandbox + per-sandbox traces / audit

Related concepts

• provisioned by → Sandbox-spec (template) + Bootstrap (single-use enrollment)
• runs against → Keyring (its specific materialized policy)
• enforces via → Layer (5 chokepoints)
• emits to → Audit / Trace (per-sandbox stream)
• identified as → Identity (sandbox token = scoped agent principal)

Authoritative docs

Topic	File
Vision	governed-agents-architecture.md §11 (enrollment), §15 (reference impls)
Lifecycle (host side)	host-runtime-cli
Lifecycle (operator side)	operator-cli
Reference example	collibra-reference-agent

Status snapshot

Aspect	Status
Sandbox-spec primitive	concept (Q3 2026)
Bootstrap flow	concept (Q3 2026)
Host runtime CLI	concept (Q3 2026; critical-path M)
Layer appliers	concept (Q3-Q4 2026)
Quick-start sandbox-specs	concept (Q4 2026, demand-driven)

Common confusions

• Sandbox ≠ Sandbox-spec. Sandbox is the running instance; Sandbox-spec is the template that produced it. One spec produces many sandboxes.
• Sandbox ≠ OS sandbox. "Sandbox" in TapPass means the logical agent installation (identity + keyring + namespace). The OS-level isolation is one of its layers (Layer 1, kernel) — not the whole concept.
• One sandbox per host machine? No. Multiple sandboxes can co-exist on one host (each with own namespace + UID + keyring). Cross-sandbox isolation is enforced.