AI Agent Sandbox Runtime and Harnesses
The sandbox is the product. Harnesses are tools inside the sandbox.
Do not describe this blueprint as an OpenCode integration, a Codex integration, or a Claude integration. A service instance asks the operator for runtime capabilities. The operator answers through GET /api/capabilities.
Runtime backends
Sandbox creation accepts metadata_json.runtime_backend:
| Value | Meaning |
|---|---|
docker | Default path. The operator starts a sidecar container. |
firecracker | MicroVM path through the in-process microvm-runtime driver. |
tee | Confidential runtime path. TEE instance mode requires attestation before service activation. |
Firecracker is driven by the operator binary. There is no separate host-agent service. Operators must provide the Firecracker binary, kernel, rootfs, socket/state paths, TAP/vsock support, and a guest metadata daemon inside the rootfs.
TEE mode needs a provider backend such as Phala, AWS Nitro, GCP Confidential Space, Azure SKR, or direct operator-managed hardware. Direct TDX currently does not give nonce-bound remote DCAP quotes in this runtime; use SEV-SNP, Nitro, Phala, GCP, or Azure when clients need nonce-bound verification.
Capability discovery
The current operator API returns two categories:
| Capability | Meaning |
|---|---|
computer_use | Enables browser/computer-use sidecar services. |
all_harness | Requests the all-harness sidecar runtime. |
The current all-harness sidecar in this repo installs:
| Harness | ID |
|---|---|
| Claude Code | claude-code |
| Codex | codex |
| opencode | opencode |
| Kimi Code | kimi-code |
| Gemini CLI | gemini |
This list is not the blueprint ABI. It is the operator’s advertised capability set. A new sidecar image can add or remove harnesses while the blueprint jobs stay the same.
Sidecar image
The public all-harness image is built from the blueprint repo:
docker build -f sidecar/Dockerfile.all-harness \
-t ghcr.io/tangle-network/blueprint-sidecar:all-harness .Operators can verify the installed harness binaries:
docker run --rm --entrypoint blueprint-verify-harnesses \
ghcr.io/tangle-network/blueprint-sidecar:all-harnessFor smaller images, build with BLUEPRINT_HARNESSES=codex,gemini or another subset. The app should still read /api/capabilities; it should not infer support from the image tag alone.
AI credentials
Sandbox lifecycle can work without model keys. Agent prompts, tasks, and workflow steps need whatever secret the selected harness or provider expects.
Operators should scope provider keys to the service instance. The blueprint ABI should not change when a new provider or harness is added.
Common credential locations remain harness-specific:
| Harness family | Typical config |
|---|---|
| Claude Code | /root/.claude or ANTHROPIC_API_KEY style provider config. |
| Codex | /root/.codex or OpenAI provider config. |
| opencode | /root/.config/opencode, /root/.opencode, or opencode provider env. |
| Kimi | /root/.kimi or /root/.config/kimi. |
| Gemini | /root/.gemini or Google provider config. |
The operator protects the session token, sidecar auth token, provider keys, and sandbox secrets. Losing one of those is a product incident, not a docs footnote.
Runtime health
Use these probes before routing users into a sandbox:
| Endpoint | What it proves |
|---|---|
/health | Runtime and state-store health. Returns degraded when a subsystem fails. |
/readyz | Strict readiness. Returns 503 unless all required subsystems are healthy. |
/api/capabilities | The runtime and harness features the operator says are available. |
| Product operation probe | A real exec, prompt, terminal, port, or workflow call through the operator API. |
The indexer can tell the app that a service exists. It cannot tell the app that a sidecar is usable right now.