Skip to content

Commit 0791965

Browse files
drewstonedrewstone
authored
docs(blueprints): rewrite product docs voice
Rewrite the Blueprint docs section in a plain technical voice and repair broken source links so the docs link check passes.
1 parent 55128a0 commit 0791965

28 files changed

Lines changed: 1108 additions & 602 deletions

‎pages/blueprints/ai-agent-sandbox/dapp-and-indexer.mdx‎

Lines changed: 50 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,69 @@
11
---
22
title: AI Agent Sandbox Dapp and Indexer
3-
description: Dapp metadata, iframe policy, and indexer requirements for the AI Agent Sandbox blueprint.
3+
description: Dapp metadata, iframe policy, indexed state, and live health boundaries for AI Agent Sandbox.
44
---
55

6-
# Dapp and Indexer
6+
# AI Agent Sandbox Dapp and Indexer
77

8-
The dapp should resolve the sandbox blueprint from first-party metadata, then render the hosted sandbox app through the trusted iframe path.
8+
Tangle Cloud should launch the hosted sandbox app from metadata, then keep the raw protocol page one click away.
99

10-
## Metadata Contract
10+
The hosted app owns the sandbox UX. The protocol page owns raw state inspection.
1111

12-
| Field | Value |
12+
## Metadata the dapp should use
13+
14+
| Field | Current value in repo metadata |
1315
| --------------------------------- | ----------------------------------------------- |
1416
| `blueprintUi.displayName` | `AI Agent Sandbox` |
1517
| `blueprintUi.requestedSlug` | `ai-agent-sandbox` |
1618
| `blueprintUi.publisher.namespace` | `tangle` |
17-
| `resources.serviceNoun` | `sandbox fleet` |
18-
| `resources.resourceNoun` | `agent` |
19-
| `externalApp.url` | `https://agent-sandbox.blueprint.tangle.tools/` |
2019
| `externalApp.mode` | `iframe` |
20+
| `externalApp.url` | `https://agent-sandbox.blueprint.tangle.tools/` |
21+
22+
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.
23+
24+
## Indexed state
25+
26+
| State | Why the dapp needs it |
27+
| --------------------------------------- | ----------------------------------------------------------- |
28+
| Blueprint creation and metadata updates | Find the sandbox blueprint and app policy. |
29+
| Operator registration | Show available operators and capacity choices. |
30+
| Service requests and approvals | Show provisioning progress. |
31+
| Service instances | Link the hosted app to the selected instance. |
32+
| Source acknowledgement | Show which runnable artifact an operator accepted. |
33+
| Jobs | Show lifecycle and workflow commands. |
34+
| Heartbeats | Separate "not ready yet" from "operator stopped reporting." |
35+
36+
The indexer should preserve enough history to distinguish pending provisioning from operator failure. The hosted app should not have to guess.
37+
38+
## Live checks
39+
40+
Indexed state is not enough to open a terminal or inject a secret. Before showing a sandbox as usable, the app should check:
41+
42+
1. operator API reachability
43+
2. session auth challenge/session flow
44+
3. `/readyz` or `/health`
45+
4. `/api/capabilities`
46+
5. one product operation when the page needs it, such as listing sandboxes or reading instance state
47+
48+
For TEE mode, the app should also expose attestation status and avoid presenting confidential execution as verified when attestation is missing.
2149

22-
The metadata defines three modes: cloud, dedicated instance, and TEE instance. The dapp can use those mode records to keep the app surface stable while routing service creation to the right blueprint ID.
50+
## Iframe policy
2351

24-
## Iframe Policy
52+
The sandbox app is iframe-first. The parent dapp should:
2553

26-
The sandbox app requests read account access, chain switching, and message/contract permissions for local and Base Sepolia deployments. Popups are disabled. The dapp should still enforce the host allowlist and iframe app policy before rendering.
54+
| Rule | Reason |
55+
| --------------------------------------------------------------- | --------------------------------------------------------------------------- |
56+
| Restrict iframe hosts to trusted suffixes and manifest entries. | Prevent arbitrary operator metadata from embedding a hostile app. |
57+
| Pass parent origin and chain context explicitly. | Lets the child app request wallet operations through the parent. |
58+
| Keep wallet approval in the parent. | Users should see the same wallet confirmation model across Tangle Cloud. |
59+
| Keep a link to raw protocol state. | Operators and support need chain/indexer state when the hosted app is down. |
2760

28-
## Indexed State
61+
## Bad copy to avoid
2962

30-
The dapp needs indexed state for:
63+
Do not name the product after one harness. The sandbox may run opencode, Codex, Claude Code, Kimi, Gemini, or another advertised runtime, but the product is the sandbox service instance and operator API.
3164

32-
| State | Why it matters |
33-
| ------------------------------ | -------------------------------------------------------- |
34-
| Blueprint creation and updates | Finds the sandbox blueprint and reads current metadata. |
35-
| Operator registration | Shows available operators and capacity choices. |
36-
| Service creation and approval | Identifies active sandbox fleets or dedicated instances. |
37-
| Source acknowledgement | Confirms the operator accepted the runnable artifact. |
38-
| Job events | Shows sandbox create/delete and workflow activity. |
39-
| Quality-of-service heartbeats | Shows liveness and operator reliability. |
65+
Use capability language instead:
4066

41-
The indexer should preserve enough service-instance and operator history for the app to distinguish "not provisioned yet" from "operator failed to report readiness." Live sandbox health still comes from the operator API and runtime checks.
67+
- "This operator advertises `all_harness` support."
68+
- "This sidecar currently lists Claude Code, Codex, opencode, Kimi Code, and Gemini CLI."
69+
- "The exact harness list comes from `/api/capabilities`."

‎pages/blueprints/ai-agent-sandbox/index.mdx‎

Lines changed: 54 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,71 @@
11
---
22
title: AI Agent Sandbox Blueprint
3-
description: First-party Tangle blueprint for managed AI agent sandboxes.
3+
description: First-party Tangle blueprint for isolated AI agent sandboxes.
44
---
55

66
# AI Agent Sandbox Blueprint
77

8-
The AI Agent Sandbox blueprint defines the template for isolated agent sandbox service instances on Tangle. Operators run the sandbox runtime and sidecar containers. Users create sandboxes, trigger workflows, attach terminals, inject secrets, and inspect execution through the hosted app.
8+
AI Agent Sandbox lets a user create an isolated agent workspace through Tangle.
9+
10+
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.
911

1012
Source repo: https://github.com/tangle-network/ai-agent-sandbox-blueprint
1113

12-
## Product Shape
14+
## What happens when a user creates a sandbox
15+
16+
1. The user chooses a sandbox mode and requests a service instance.
17+
2. The selected operator approves the request.
18+
3. The operator starts the runtime and reports provisioning state.
19+
4. The app authenticates to the operator API with EIP-191 challenge signing and a PASETO session token.
20+
5. The user works through the hosted app: terminal, files, workflows, prompts, tasks, ports, SSH, secrets, and snapshots.
21+
22+
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.
23+
24+
## Modes
25+
26+
| Mode | Blueprint ID in current metadata | Service shape |
27+
| ------------------ | -------------------------------- | ----------------------------------------------------------------------------- |
28+
| Cloud | `10` | A fleet-style sandbox service. Users create and delete sandboxes on demand. |
29+
| Dedicated instance | `11` | One sandbox per service instance. The operator auto-provisions it on startup. |
30+
| TEE instance | `12` | Dedicated instance with TEE attestation and sealed-secret support. |
31+
32+
Mode IDs come from the repo metadata. Treat them as network-specific config, not hard-coded truth for every chain.
33+
34+
## Jobs
35+
36+
| Job | Mode | Purpose |
37+
| ------------------ | ------------------ | ---------------------------------------------------- |
38+
| `SANDBOX_CREATE` | Cloud | Create a sandbox container or runtime instance. |
39+
| `SANDBOX_DELETE` | Cloud | Delete the sandbox and clean up runtime attachments. |
40+
| `WORKFLOW_CREATE` | Cloud and instance | Register a workflow template. |
41+
| `WORKFLOW_TRIGGER` | Cloud and instance | Trigger a workflow against the service instance. |
42+
| `WORKFLOW_CANCEL` | Cloud and instance | Cancel an active workflow. |
43+
44+
The internal workflow tick is scheduler-driven and should not be treated as a public on-chain job.
1345

14-
| Area | Source-backed behavior |
15-
| ----------------- | --------------------------------------------------------------------------------------------------------- |
16-
| Cloud mode | Multi-tenant fleet; callers create and delete sandboxes on demand through on-chain jobs. |
17-
| Instance mode | One sandbox per service instance; the operator auto-provisions on startup and reports lifecycle directly. |
18-
| TEE instance mode | Dedicated instance with TEE attestation and sealed secrets. |
19-
| Hosted app | `https://agent-sandbox.blueprint.tangle.tools/` |
20-
| Metadata identity | `publisher.namespace = "tangle"`, `requestedSlug = "ai-agent-sandbox"` |
46+
## Read and control surface
2147

22-
## On-Chain Jobs
48+
The operator API owns the live product state:
2349

24-
| ID | Job | Mode | What it does |
25-
| --- | ------------------ | ------------------ | ------------------------------------------------------------ |
26-
| `0` | `SANDBOX_CREATE` | Cloud | Creates a sandbox container, microVM, or TEE-backed sandbox. |
27-
| `1` | `SANDBOX_DELETE` | Cloud | Deletes the sandbox and releases runtime resources. |
28-
| `2` | `WORKFLOW_CREATE` | Cloud and instance | Registers a workflow template. |
29-
| `3` | `WORKFLOW_TRIGGER` | Cloud and instance | Starts a registered workflow. |
30-
| `4` | `WORKFLOW_CANCEL` | Cloud and instance | Cancels active workflow execution. |
50+
| API area | Examples |
51+
| ------------------ | --------------------------------------------------- |
52+
| Auth | challenge, session, revoke |
53+
| Sandbox operations | list, exec, prompt, task, stop, resume, snapshot |
54+
| Access | SSH key provision/revoke, port proxy |
55+
| Secrets | inject and wipe sandbox-scoped secrets |
56+
| Health | `/health`, `/readyz`, `/metrics` |
57+
| Capabilities | `/api/capabilities` for runtime and harness support |
3158

32-
`JOB_WORKFLOW_TICK` is internal cron-driven workflow progress. It is not a public on-chain job.
59+
Every data endpoint requires a signed wallet session. Production operators must set `SESSION_AUTH_SECRET`; otherwise sessions and encrypted secrets re-key on restart.
3360

34-
## Read Next
61+
## What to read next
3562

36-
| Page | Use it for |
37-
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
38-
| [Operator Requirements](/blueprints/ai-agent-sandbox/operator-requirements) | Host sizing, env vars, Docker, Firecracker, TEE, ports. |
39-
| [Runtime and Harnesses](/blueprints/ai-agent-sandbox/runtime-and-harnesses) | Sidecar capabilities, harness discovery, secrets, auth, runtime safety. |
40-
| [Dapp and Indexer](/blueprints/ai-agent-sandbox/dapp-and-indexer) | Metadata, iframe policy, indexed events, service state. |
63+
| Page | Use it for |
64+
| --------------------------------------------------------------------------- | ------------------------------------------------------------------- |
65+
| [Operator Requirements](/blueprints/ai-agent-sandbox/operator-requirements) | Host setup, ports, Docker, Firecracker, TEE, state, and secrets. |
66+
| [Runtime and Harnesses](/blueprints/ai-agent-sandbox/runtime-and-harnesses) | Runtime backends, capability discovery, harnesses, and AI keys. |
67+
| [Dapp and Indexer](/blueprints/ai-agent-sandbox/dapp-and-indexer) | Metadata, iframe policy, indexed state, and live health boundaries. |
4168

42-
## Source Material
69+
## Sources used
4370

44-
This page is based on the blueprint repo's `README.md`, `docs/runbook.md`, `metadata/blueprint-metadata.json`, `ai-agent-sandbox-blueprint-lib/src/lib.rs`, `sandbox-runtime/src/operator_api.rs`, and `TEE-GUIDE.md`.
71+
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.

0 commit comments

Comments
 (0)