AI Agent Sandbox Blueprint
AI Agent Sandbox lets a user create an isolated agent workspace through Tangle.
The blueprint defines the jobs, metadata, contracts, and runtime rules. Operators run the actual sandboxes: Docker containers, Firecracker microVMs, or TEE-backed instances. The hosted app gives users terminals, workflows, files, port proxies, secrets, snapshots, and prompt/task execution.
Source repo: https://github.com/tangle-network/ai-agent-sandbox-blueprint
What happens when a user creates a sandbox
- The user chooses a sandbox mode and requests a service instance.
- The selected operator approves the request.
- The operator starts the runtime and reports provisioning state.
- The app authenticates to the operator API with EIP-191 challenge signing and a PASETO session token.
- The user works through the hosted app: terminal, files, workflows, prompts, tasks, ports, SSH, secrets, and snapshots.
The on-chain path records lifecycle and workflow commands. The operator API handles live I/O. That split is intentional: terminal output and file lists should not be blockchain jobs.
Modes
| Mode | Blueprint ID in current metadata | Service shape |
|---|---|---|
| Cloud | 10 | A fleet-style sandbox service. Users create and delete sandboxes on demand. |
| Dedicated instance | 11 | One sandbox per service instance. The operator auto-provisions it on startup. |
| TEE instance | 12 | Dedicated instance with TEE attestation and sealed-secret support. |
Mode IDs come from the repo metadata. Treat them as network-specific config, not hard-coded truth for every chain.
Jobs
| Job | Mode | Purpose |
|---|---|---|
SANDBOX_CREATE | Cloud | Create a sandbox container or runtime instance. |
SANDBOX_DELETE | Cloud | Delete the sandbox and clean up runtime attachments. |
WORKFLOW_CREATE | Cloud and instance | Register a workflow template. |
WORKFLOW_TRIGGER | Cloud and instance | Trigger a workflow against the service instance. |
WORKFLOW_CANCEL | Cloud and instance | Cancel an active workflow. |
The internal workflow tick is scheduler-driven and should not be treated as a public on-chain job.
Read and control surface
The operator API owns the live product state:
| API area | Examples |
|---|---|
| Auth | challenge, session, revoke |
| Sandbox operations | list, exec, prompt, task, stop, resume, snapshot |
| Access | SSH key provision/revoke, port proxy |
| Secrets | inject and wipe sandbox-scoped secrets |
| Health | /health, /readyz, /metrics |
| Capabilities | /api/capabilities for runtime and harness support |
Every data endpoint requires a signed wallet session. Production operators must set SESSION_AUTH_SECRET; otherwise sessions and encrypted secrets re-key on restart.
What to read next
| Page | Use it for |
|---|---|
| Operator Requirements | Host setup, ports, Docker, Firecracker, TEE, state, and secrets. |
| Runtime and Harnesses | Runtime backends, capability discovery, harnesses, and AI keys. |
| Dapp and Indexer | Metadata, iframe policy, indexed state, and live health boundaries. |
Sources used
This page is grounded in the repo README.md, docs/runbook.md, TEE-GUIDE.md, metadata/blueprint-metadata.json, sandbox-runtime/src/operator_api.rs, and the sidecar image docs.