Human HTTP Integration
The control-plane workflow: how an operator (or a provisioning script / control-plane service) creates the resources agents then use — an agent identity and the SandFS instances it owns. Every example on this page is runnable curl against a deployed gateway. The complete endpoint reference — every field, status code, and error body — is the Human API Reference.
1. Where this fits
operator / control plane agent process
│ │
│ POST /human/agent │
│◀── agent_id + api_key (once) │
│ POST /human/sandfs │
│◀── sandfs_id │
│ (hand sandfs_id to agent) │
│ ▼
└──────────────────────▶ POST /agent/execute (api_key + sandfs_id)
Everything on the left is the human listener (:3100 in distributed mode); everything on the right is the agent listener. The two never mix: agents cannot call /human/*, and the operator’s credentials are not the agent’s API key.
2. Quickstart
Two calls stand up a working sandbox (auth disabled — the dev default; with OIDC configured add -H "Authorization: Bearer $TOKEN" to every call, see Auth Integration):
GW=https://sandswap.local:3100 # human listener; single-node: :3100 on the gateway
# 1. Create the agent identity — the API key is returned EXACTLY once.
curl -sS -X POST "$GW/human/agent" \
-H 'Content-Type: application/json' -d '{"name": "my-agent"}'
{"agent_id":"agent-1a2b3c4d","api_key":"sk-sandswap-agent-9f…64-hex","name":"my-agent"}
# 2. Create the SandFS the agent will run in.
curl -sS -X POST "$GW/human/sandfs" \
-H 'Content-Type: application/json' \
-d '{"agent_id":"agent-1a2b3c4d","template":"ubuntu:24.04","mode":"flat"}'
{"sandfs_id":"sandfs-8e4f2a91","agent_id":"agent-1a2b3c4d","name":"unnamed-sandfs",
"description":"","rootfs_path":"/var/sandswap/volumes/sf-…","template":"ubuntu:24.04",
"pull_status":"cached"}
Hand sandfs_id + api_key to the agent process; from then on the agent executes through the agent API. The first create from a template ref that is not in the local store reports "pull_status":"pulled" — the template was fetched from the OCI registry on demand (Registry).
3. Creating an agent
POST /human/agent with {"name": "..."} (a missing name defaults to unnamed-agent) returns 201 with agent_id, name, and api_key.
- The key (
sk-sandswap-agent-+ 64 hex chars fromcrypto/rand) is returned exactly once — store it at creation time. The identity store keeps only its hash, so a lost key means deleting and re-creating the agent (which deletes its SandFS instances too). - Generation is fail-fast: an unavailable system PRNG aborts the request rather than ever issuing a predictable or shared key.
sandctl api agent create --name ...wraps this call and caches the key locally for convenience.
4. Creating a SandFS
POST /human/sandfs — the fields that matter:
| Field | Notes |
|---|---|
agent_id | required — the owner. Every subsequent agent call against this SandFS is authorized against this binding. |
template | a template ref (base:v1, sqlite:v1, ubuntu:24.04, …). See Templates and building your own. |
mode | flat (writable copy, OS package managers work) or overlay (read-only shared base + writable workspace/, least privilege, no OS packages). Required — not auto-detected. |
name, description | optional; the description (≤ 200 chars) is what the agent sees in GET /agent/sandfs / list_sandfs — write it for the LLM that will pick the sandbox. |
vcpus, memory_mb | optional minimum resources; 0 inherits the template default. |
Mode choice is also the security posture: overlay drops all capabilities in-guest (language packages still install to /home/agent and persist); flat keeps ambient capabilities so apt works. The common pattern: build in a flat SandFS, save-template, run production instances in overlay.
5. How ids stay unique
You never choose agent_id or sandfs_id — the gateway mints both:
- Format:
agent-xxxxxxxx/sandfs-xxxxxxxx— 8 hex chars (32 random bits) from a UUID. - The etcd record key is the id (
sandfs/<id>), so an existing-key check is the authoritative collision test; on collision the gateway regenerates and retries (bounded draws) instead of failing the create. - The on-disk volume directory is not the id: names are derived (
sf-+ HMAC of the deployment seed — isolation §4), so the record’srootfs_pathis the only supported way to learn a host path. Never construct<volumes>/<sandfs-id>.
Treat ids as opaque stable addressing: hand them out once at provisioning time (GET /agent/sandfs is the agent’s own discovery path) and don’t re-derive them.
6. Listing and lifecycle polling
The fleet-wide list endpoints are cursor-paginated (a million-record fleet never materializes in one response):
curl -sS "$GW/human/sandfs?limit=100" # first page
curl -sS "$GW/human/sandfs?limit=100&cursor=$NEXT" # next page
{"items":[{"sandfs_id":"sandfs-8e4f2a91","agent_id":"agent-1a2b3c4d",
"name":"unnamed-sandfs","description":"","rootfs_path":"/var/sandswap/volumes/sf-…",
"template":"ubuntu:24.04","mode":"flat","min_vcpus":0,"min_memory_mb":0,
"created_at":"2026-10-14T09:00:00Z","status":""}],
"next_cursor":"sandfs-9a…","truncated":true}
statusis the lifecycle state:""= active;detaching/detachedmid template swap;deletingmid deletion.GET /human/sandfs/{id}is the single-record polling endpoint for those transitions.- The last page omits
next_cursor. Iteration order is ascending by ID.
7. Multi-tenant provisioning: namespaces
The tenancy surface /human/ns/{ns}/… mirrors agent and SandFS CRUD one level deeper — a token scoped by the sandswap_ns claim can only touch its own namespaces:
curl -sS -X POST "$GW/human/ns/acme/agent" \
-H 'Content-Type: application/json' -d '{"name": "acme-agent"}'
curl -sS -X POST "$GW/human/ns/acme/sandfs" \
-H 'Content-Type: application/json' \
-d '{"agent_id":"agent-…","template":"ubuntu:24.04","mode":"overlay"}'
Rule 1 (path grant): a namespace not in the caller’s sandswap_ns claim is 403 NAMESPACE_FORBIDDEN. Rule 2 (record match): a cross-namespace id is a uniform 404 — no enumeration oracle. The unscoped fleet-wide routes require the * grant (403 FLEET_SCOPE_REQUIRED otherwise). The full model: Namespaces.
8. Day-2 operations from the control plane
- Templates: pull/push/save-template/delete — the lifecycle and the in-use guard are in Registry and building/templates.
- Template upgrade in place:
detach-template→attach-template(or the one-shotswap-template) re-points an overlay SandFS at a new template whileworkspace/andhome/carry over — the workflow andhomepolicies are in the Human API Reference. - Maintenance window:
POST /human/maintenance{"on":true,"reason":"…"}— agent traffic is refused503 MAINTENANCEcluster-wide (no restarts); flipon:falseto resume. Used around storage moves such as the volume-seed rotation. - Ownership recovery:
POST /human/ownership/release/{sandfs_id},reap-stuck,reap-stuck-node— the operator backstops behind the automatic resilience machinery; semantics and guards in Resilience and the reference. - Deletion is cascading: deleting an agent deletes all SandFS it owns (volumes + records). Deleting a SandFS first flips it
deleting, drains every mount, then removes storage + record + ownership key. - Observability:
/stats(cluster view of every gateway/node/VM) and/metrics(same data, Prometheus format — Prometheus Integration).