Skip to content

docs(blueprints): rewrite product docs voice #149

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
drewstone merged 2 commits into from
Jun 14, 2026
Merged

docs(blueprints): rewrite product docs voice #149

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4dc1e03
docs(blueprints): rewrite product docs voice
drewstone Jun 14, 2026
be71066
docs(links): repair broken source references
drewstone Jun 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 50 additions & 22 deletions pages/blueprints/ai-agent-sandbox/dapp-and-indexer.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,41 +1,69 @@
---
title: AI Agent Sandbox Dapp and Indexer
description: Dapp metadata, iframe policy, and indexer requirements for the AI Agent Sandbox blueprint.
description: Dapp metadata, iframe policy, indexed state, and live health boundaries for AI Agent Sandbox.
---

# Dapp and Indexer
# AI Agent Sandbox Dapp and Indexer

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

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

| Field | Value |
## 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` |
| `resources.serviceNoun` | `sandbox fleet` |
| `resources.resourceNoun` | `agent` |
| `externalApp.url` | `https://agent-sandbox.blueprint.tangle.tools/` |
| `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.

## Indexed 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 indexer should preserve enough history to distinguish pending provisioning from operator failure. The hosted app should not have to guess.

## Live checks

Indexed state is not enough to open a terminal or inject a secret. Before showing a sandbox as usable, the app should check:

1. operator API reachability
2. session auth challenge/session flow
3. `/readyz` or `/health`
4. `/api/capabilities`
5. 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.

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.
## Iframe policy

## Iframe Policy
The sandbox app is iframe-first. The parent dapp should:

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.
| 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/indexer state when the hosted app is down. |

## Indexed State
## Bad copy to avoid

The dapp needs indexed state for:
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.

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

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.
- "This operator advertises `all_harness` support."
- "This sidecar currently lists Claude Code, Codex, opencode, Kimi Code, and Gemini CLI."
- "The exact harness list comes from `/api/capabilities`."
81 changes: 54 additions & 27 deletions pages/blueprints/ai-agent-sandbox/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,44 +1,71 @@
---
title: AI Agent Sandbox Blueprint
description: First-party Tangle blueprint for managed AI agent sandboxes.
description: First-party Tangle blueprint for isolated AI agent sandboxes.
---

# AI Agent Sandbox Blueprint

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.
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

## Product Shape
## What happens when a user creates a sandbox

1. The user chooses a sandbox mode and requests a service instance.
2. The selected operator approves the request.
3. The operator starts the runtime and reports provisioning state.
4. The app authenticates to the operator API with EIP-191 challenge signing and a PASETO session token.
5. 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.

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

## On-Chain Jobs
The operator API owns the live product state:

| ID | Job | Mode | What it does |
| --- | ------------------ | ------------------ | ------------------------------------------------------------ |
| `0` | `SANDBOX_CREATE` | Cloud | Creates a sandbox container, microVM, or TEE-backed sandbox. |
| `1` | `SANDBOX_DELETE` | Cloud | Deletes the sandbox and releases runtime resources. |
| `2` | `WORKFLOW_CREATE` | Cloud and instance | Registers a workflow template. |
| `3` | `WORKFLOW_TRIGGER` | Cloud and instance | Starts a registered workflow. |
| `4` | `WORKFLOW_CANCEL` | Cloud and instance | Cancels active workflow execution. |
| 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 |

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

## Read Next
## What to read next

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

## Source Material
## Sources used

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`.
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.
Loading
Loading