HTTP API

There is no intentic API in the cloud that reaches your code. The platform stores your identity and your sandbox's address and nothing else; the API on this page is served by your daemon, inside your container, and the only way in is a credential you minted.

This page is long and you probably want one part of it:

Where it is#

Each sandbox answers on its own hostname, https://sandbox-<id>.<zone>, over its private Cloudflare tunnel. The app shows the exact URL on Sandbox → Overview. One route is deliberately open — /health, the "is a daemon there" probe every launch script and readiness loop makes.

curl https://sandbox-a1b2c3d4e5f6.intentic.dev/health

{ "ok": true, "sandboxId": "a1b2c3d4e5f6", "boot": { … }, "announce": { … } }

The sandbox id in that answer is how a caller proves it reached this daemon rather than something else on the same port. On the machine running the sandbox there is also https://local-<id>.<zone>, a public DNS name that resolves to 127.0.0.1 — a real certificate on a loopback address, so a browser on that machine skips the round trip to Cloudflare and back.

How a call is authorized#

Two kinds of caller, two credentials, and the difference is whether a person is present.

A person, in a browser#

The sandbox authenticates the end user directly against Google: the browser presents a Google ID token, and the daemon verifies its signature against Google's published keys. The platform never holds or signs this credential, so a platform compromise cannot command your sandbox. The first verified identity to arrive becomes the owner; further people are granted access by the owner, with a role that decides how far they reach.

POST /system/session exchanges that token for a daemon-minted session, which is what every steady-state call presents as authorization: Bearer …. Calling it again with a still-valid session renews it.

A program, anywhere#

Anything outside a browser presents a control token in the x-intentic-control header instead. A control token is shown to you exactly once at mint — the daemon keeps only its hash — and it can be revoked individually at any time.

curl -X POST "$SANDBOX/system/control/tokens" \
  -H "authorization: Bearer $OWNER_SESSION" \
  -H "content-type: application/json" \
  -d '{"label":"nightly CI","scope":"read"}'

{ "id": "6f1c…", "token": "ict_9wQ…" }

The app mints one for you on Sandbox → Computers → Editor bridge, at editor scope, together with the settings snippet an ACP editor needs. Any other scope is minted through the route above, which requires an owner session.

What a scope reaches#

Worth saying plainly: at drive and above, a stolen token is the agent's reach, because driving an agent means editing files and running commands in this sandbox. read is the one that is genuinely narrower, which is why it exists separately rather than as a politeness. A token presented on a route outside its scope gets a 403 that says so, rather than a confusing 401.

The shape of a call#

The API is described by a typed contract that the daemon implements and the browser is built against, served over OpenAPI. That has one consequence worth internalising: the contract's path is the URL, there is no envelope, and the body you send and the body you get back are the declared shapes.

SANDBOX=https://sandbox-a1b2c3d4e5f6.intentic.dev

# GET — input rides the query string
curl "$SANDBOX/workspace/file?path=README.md" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

# Everything else — input rides the JSON body, including DELETE
curl -X POST "$SANDBOX/git/root/commit" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"message":"fix the flaky test"}'

# Start a turn. It answers as soon as the run exists — the work is detached.
curl -X POST "$SANDBOX/agent" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"prompt":"Update the changelog for the last five commits.",
       "conversationId":"nightly-changelog",
       "isolated":true}'

{ "run": "run_8c2f…" }

# Watch it: server-sent events, from the start or from a cursor you kept.
curl -N -X POST "$SANDBOX/agent/attach" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"conversationId":"nightly-changelog","after":0}'

curl -N "$SANDBOX/events" -H "authorization: Bearer $SESSION"

data: {"kind":"hello","workspaceId":"…","routes":["agent.run","git.status", …],"build":"…"}

data: {"kind":"heartbeat"}

data: {"kind":"workspaceChanged","paths":["src/app.ts","README.md"]}

data: {"kind":"refsChanged","repos":["root"]}