Streams
10 routes answer a stream rather than a value: a turn as it happens, the sandbox's own live feed, and the operations that take minutes. They are server-sent events, and reading one takes no library.
On this page(4 sections)
How to read one
A stream is a response that stays open. Frames are separated by a blank line and each carries one data: line holding JSON. Anything that can read a line can read one; in a browser it is EventSource for the GET routes and a plainfetch reader for the POST ones.
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"]}The -N matters. Without it the output is buffered, so a stream you are watching arrives in silence and then all at once, which looks exactly like a route that does not work.
Which routes stream
Found from the contract rather than listed here, so this table cannot fall behind: a route streams when it answerstext/event-stream, and every one that does is below.
| Route | Carries | Group |
|---|---|---|
POST /agent/attach | Watch a turn happen | One agent |
POST /capabilities | Connect something, or change a connection | Capabilities |
POST /vpn/{id}/connect | Dial a VPN | VPN |
POST /exit/{id}/start | Bring an exit up | Exit locations |
POST /exit/{id}/use | Move to another country | Exit locations |
POST /exit/{id}/rotate | Take a different address, same country | Exit locations |
POST /intentic | Run an infrastructure command | Platform CLI |
GET /intentic/apply/events | Follow the reconcile | Platform CLI |
GET /events | The live event stream | System |
POST /system/computers/{id}/sandboxes/{slug} | Drive a sandbox on one of your own computers | System |
The sandbox-wide feed
GET /events is the one to hold open for as long as your program runs. It carries the sandbox's liveness and everything that changed out of band: an opening frame naming this daemon and the routes it implements, heartbeats, boot progress, batches of changed file paths, which repositories' branches moved, the roster of who else is looking, and the fleet.
Those change pushes are not a nicety. An intentic workspace is file-first: the agent edits files and moves branches with its own tools, entirely out of band from every route in this reference. Without the feed, a client is only ever as fresh as the last thing somebody clicked.
The one that is a WebSocket
GET /system/terminal carries a terminal session's raw bytes, and it is a WebSocket rather than an event stream because the traffic goes both ways: you type into it. A WebSocket cannot set headers, so it authorises with a short-lived ticket in the query string instead of the credential every other route takes. It is not in this reference for the same reason the byte routes are not: it is not a JSON contract and cannot be described as one.