AI Agent Sandbox Dapp Integration
Tangle Cloud should launch the hosted sandbox app from metadata, then keep the raw protocol page one click away.
The hosted app owns the sandbox UX. The protocol page owns raw state inspection.
The AI Agent Sandbox repo does not ship a dedicated indexer today. Treat protocol state as data the dapp can read from contracts or a shared protocol indexing layer when one is available. Do not make an indexer part of the blueprint operator path.
Metadata the dapp should use
| Field | Current value in repo metadata |
|---|---|
blueprintUi.displayName | AI Agent Sandbox |
blueprintUi.requestedSlug | ai-agent-sandbox |
blueprintUi.publisher.namespace | tangle |
externalApp.mode | iframe |
externalApp.url | https://agent-sandbox.blueprint.tangle.tools/ |
The metadata also declares cloud, dedicated instance, and TEE instance modes. Use those records to route service creation to the right blueprint ID for the selected network.
Protocol state
| State | Why the dapp needs it |
|---|---|
| Blueprint creation and metadata updates | Find the sandbox blueprint and app policy. |
| Operator registration | Show available operators and capacity choices. |
| Service requests and approvals | Show provisioning progress. |
| Service instances | Link the hosted app to the selected instance. |
| Source acknowledgement | Show which runnable artifact an operator accepted. |
| Jobs | Show lifecycle and workflow commands. |
| Heartbeats | Separate “not ready yet” from “operator stopped reporting.” |
The dapp should preserve enough protocol history to distinguish pending provisioning from operator failure. That history can come from direct chain reads, a shared protocol indexer, or another canonical protocol-state service. It is not a separate component shipped by this blueprint.
Live checks
Protocol state is not enough to open a terminal or inject a secret. Before showing a sandbox as usable, the app should check:
- operator API reachability
- session auth challenge/session flow
/readyzor/health/api/capabilities- one product operation when the page needs it, such as listing sandboxes or reading instance state
For TEE mode, the app should also expose attestation status and avoid presenting confidential execution as verified when attestation is missing.
Iframe policy
The sandbox app is iframe-first. The parent dapp should:
| Rule | Reason |
|---|---|
| Restrict iframe hosts to trusted suffixes and manifest entries. | Prevent arbitrary operator metadata from embedding a hostile app. |
| Pass parent origin and chain context explicitly. | Lets the child app request wallet operations through the parent. |
| Keep wallet approval in the parent. | Users should see the same wallet confirmation model across Tangle Cloud. |
| Keep a link to raw protocol state. | Operators and support need chain and service-instance state when the hosted app is down. |
Bad copy to avoid
Do not name the product after one harness. The Sandbox SDK supports OpenCode plus 12 peer backend types: Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, ACP, Cursor, and CLI base. The current Sandbox UI picker exposes a subset plus NanoClaw. The AI Agent Sandbox blueprint’s current all-harness sidecar advertises Claude Code, Codex, OpenCode, Kimi Code, and Gemini CLI. The product boundary is the sandbox service instance and operator API.
Use capability language instead:
- “This operator advertises
all_harnesssupport.” - “This sidecar currently lists Claude Code, Codex, OpenCode, Kimi Code, and Gemini CLI.”
- “The exact harness list comes from
/api/capabilities.”