Bootstrap

Bootstrap

A Bootstrap is a single-use, 15-min-TTL signed URL.

The operator mints it from a Sandbox-spec. The host owner runs tappass-host init --enroll-url <url> on the target machine. The bootstrap is exchanged under the host's machine identity; afterward only the resulting mTLS cert and the Compiled Policy file remain. The URL is burned.

The deployment seam between operator action and host enrollment.

At a glance

What it is	One-shot signed URL: 15-min TTL, single-use
Minted by	Operator: tappass sandbox-spec emit-bootstrap <name>
Consumed by	Host owner: tappass-host init --enroll-url <url>
Carries	Sandbox identity, TapPass's signing public key, exchange token
Outcomes	mTLS cert (host identity), Compiled Policy v1 (read-only on disk), sandbox row in control plane

The bootstrap flow

[operator]      tappass sandbox-spec emit-bootstrap collibra-steward --count 2
                → Returns: 2 URLs like https://app.tappass.ai/install/abc123, /install/def456
                → 15-min TTL each; single-use
                │
                ▼ operator hands URL to host owner (Slack, email, MDM push, …)
                │
[host owner]    pipx install tappass-host tappass-agent <agent-package>
                tappass-host init my-agent --enroll-url https://app.tappass.ai/install/abc123
                │
                ▼ host calls TapPass with the URL
                │
[tappass]       Validates: URL signature + not-expired + not-burned
                Returns: machine-identity challenge
                │
                ▼ host responds with proof of possession
                │
[tappass]       Issues mTLS cert; binds it to a fresh sandbox_id derived from the spec;
                marks URL as burned
                │
                ▼
[host owner]    tappass-host start my-agent --agent <agent-package>
                → Compiled Policy mounted RO; Provider per ring applied; agent exec'd
                → status=active on first heartbeat

What the URL is, and isn't

Is:

• Signed (Ed25519, against a publicly-pinned TapPass key)
• 15-min TTL (clock-skew tolerant ±60s)
• Single-use (server marks burned: true on first valid exchange; subsequent attempts return 410 Gone)
• Embeds: sandbox_spec_ref, org_id, signing public key, one-shot exchange token

Isn't:

• A long-lived credential. The exchange happens in the first minute; afterward only the resulting mTLS cert and the Compiled Policy file remain. The bootstrap URL is irrelevant after consumption.
• Reusable. Bootstraps can't be saved and re-used; that's an architectural property.
• Sufficient on its own. The host must have tappass-host installed before the URL can be consumed; the URL is the handoff, not the installation.

Why single-use, why 15-min TTL

Property	Why
Single-use	Prevents replay. A leaked URL is at most one host's worth of damage.
15-min TTL	Limits the window in which a leaked URL is exploitable. Operators mint just-in-time.
Signed	Host can verify the URL came from TapPass before responding. Prevents phishing-style spoofing.
Includes the public key	Host pins TapPass's signing key during the exchange, then verifies all subsequent Sync payloads against it. No external key-distribution dependency.

Two enrollment flows

Flow A — single-machine install

Production / staging. The operator mints one URL per host.

# Operator:
tappass sandbox-spec emit-bootstrap customer-support --count 1
# → https://app.tappass.ai/install/abc123

# Host owner:
pipx install tappass-host tappass-agent customer-support-agent
tappass-host init my-agent --enroll-url https://app.tappass.ai/install/abc123
tappass-host start my-agent --agent customer-support-agent

Flow B — multi-sandbox laptop simulation (development)

Local dev / demo. Multiple sandboxes scaffolded in one go via docker-compose.

tappass dev seed-sandboxes --count 3 --policy customer-support
docker-compose up

Internally the same bootstrap mechanic runs N times against ephemeral hosts.

Discovery — what about unenrolled agents?

For customers who don't yet know what agents they have, TapPass surfaces unenrolled agents passively:

• Gateway-side detection: an LLM call hits api.tappass.ai/v1 with a token that doesn't map to any active sandbox → the dashboard logs a "potential unenrolled agent" event with source IP, user-agent, and call signature.
• MCP-side detection: an MCP connection attempt to mcp.tappass.ai with no valid mcp_session_token → same surfacing.

The operator opens Discovered agents in the dashboard, sees a list of "things calling TapPass without enrollment," and one-clicks enroll this to mint a bootstrap URL targeted at the source. The URL is then handed to the appropriate host owner via the usual flow.

Engines that operate on Bootstrap

Engine	What it does	Status
Bootstrap minter	Issues N single-use URLs from a Sandbox-spec	concept (within tappass-cli)
Bootstrap consumer	Exchanges URL → mTLS cert + Compiled Policy on the host	concept (within host-runtime-cli)
Bootstrap registry	Tracks issued, burned, expired URLs per org	concept (within control plane)
Discovery surfacer	Logs unenrolled-agent signals; one-click enroll	concept (Q4 2026)

Surfaces

Persona	Surface	What you do
Operator (CLI)	tappass sandbox-spec emit-bootstrap <name> --count N	mint URLs
Operator (dashboard)	"Issue bootstrap" button on a Sandbox-spec	visual equivalent
Host owner	tappass-host init --enroll-url <url>	consume the URL
Operator	"Discovered agents" page	see unenrolled callers; one-click enroll

Related concepts

• minted from ← Sandbox-spec (template)
• produces → Sandbox (running instance) + host mTLS cert
• starts → Sync (the established mTLS cert is the channel for subsequent push)
• authenticates → Identity (host owner's machine identity, then derived sandbox identity)

Authoritative docs

Topic	File
Vision	governed-agents.md §11 — bootstrap flow + agent discovery
Privsep model	governed-agents.md §13 — why bootstrap is single-use
Component	host-runtime-cli — consumption

Common confusions

• Bootstrap ≠ enrollment ≠ activation. Bootstrap is the URL. Enrollment is exchanging the URL for mTLS (tappass-host init). Activation is first heartbeat after start (tappass-host start). Three distinct events.
• Bootstrap ≠ long-lived auth. It's a one-shot exchange. After consumption, the host's mTLS cert is the long-lived identity (refreshed hourly).
• A leaked bootstrap is bounded damage. Single-use + 15-min TTL means at most one rogue host's worth of compromise. Compare to long-lived API keys, where a leak is ongoing damage.
• Bootstrap doesn't carry the Compiled Policy. The Compiled Policy is delivered after the mTLS exchange, via Sync. The bootstrap is the seam, not the payload.