AI Agent Sandbox Operator Requirements

An AI Agent Sandbox operator is running untrusted compute for other people. Start from that fact.

The operator needs a chain identity, persistent state, a supervised runtime, and an authenticated API. If the operator exposes TEE mode or Firecracker mode, it also needs the host-level pieces those runtimes require.

Common requirements

Requirement	Why
Operator keystore	Signs protocol actions and identifies the operator.
HTTP and WebSocket RPC	Reads chain state and subscribes to events.
`BLUEPRINT_STATE_DIR`	Stores sandbox records, sessions, workflow state, and local runtime state.
`SESSION_AUTH_SECRET`	Derives PASETO session tokens and at-rest encryption keys. Required in production.
UI/API ingress auth	Prevents the public internet from directly controlling sandboxes.
Supervised process	The operator must restart cleanly after crashes.

Binary variants

Variant	Binary	Shape
Cloud sandbox	`ai-agent-sandbox-blueprint-bin`	Fleet mode. Users create/delete sandboxes.
Dedicated instance	`ai-agent-instance-blueprint-bin`	One sandbox per service instance.
TEE instance	`ai-agent-tee-instance-blueprint-bin`	Dedicated instance plus attestation and sealed secrets.

Docker mode

Docker is the simplest path.

Variable	Purpose
`SIDECAR_IMAGE`	Sidecar image, usually `ghcr.io/tangle-network/blueprint-sidecar:all-harness`.
`SIDECAR_PUBLIC_HOST` or `PUBLIC_HOST`	Public hostname used when returning sidecar or proxy URLs.
`SIDECAR_PULL_IMAGE`	Whether to pull the image on first create.
`OPERATOR_API_PORT`	Operator API port. Sandbox mode defaults around `9100`.

Keep raw sidecar ports private unless the operator intentionally proxies them.

Firecracker mode

Firecracker mode runs through the operator process and microvm-runtime.

Variable	Purpose
`MICROVM_FIRECRACKER_BIN`	Firecracker binary path.
`MICROVM_FIRECRACKER_KERNEL`	Linux kernel image used for guests.
`MICROVM_FIRECRACKER_ROOTFS`	Default ext4 rootfs.
`MICROVM_FIRECRACKER_SOCKET_DIR`	Per-VM API socket parent directory.
`MICROVM_FIRECRACKER_STATE_DIR`	Per-VM state directory.
`MICROVM_FIRECRACKER_VCPU`	Default vCPU count.
`MICROVM_FIRECRACKER_MEM_MIB`	Default memory in MiB.
`MICROVM_GUEST_METADATA_PORT`	vsock port for per-VM env and auth token injection.

The rootfs must include the guest metadata daemon. Without it, the operator cannot inject per-VM env vars and sidecar auth tokens over vsock.

TEE mode

Set TEE_BACKEND to one of:

Backend	Required setup
`phala`	`PHALA_API_KEY`; optional endpoint override.
`nitro` or `aws`	AWS region, AMI, subnet, security group, instance type, and optional KMS/profile config.
`gcp`	GCP project, zone, image, machine type, and optional service account/KMS config.
`azure`	Subscription, resource group, location, VM image/size, subnet, tenant/client secret, and optional Key Vault/attestation config.
`direct`	TDX, SEV-SNP, or Nitro-capable hardware and the matching device node.

TEE instance contracts enforce non-empty attestation when teeRequired=true. The operator API also exposes attestation and sealed-secret endpoints.

Local proof

The repo’s local runbook uses:

SKIP_BUILD=1 ./scripts/deploy-local.sh
./scripts/test-e2e.sh

The smoke should prove:

local Anvil and contracts are up
blueprints are registered
operator APIs start
auth works
lifecycle reporting reaches the chain
runtime/operator API actions hit a real sidecar path where enabled

Do not replace this with mocked API tests when deploy scripts, service registration, or auth changed.

Overview Runtime and Harnesses