The sandbox itself

System

The daemon itself: its identity, its event stream, its terminals, its browsers, its helpers

On this page(14 sections)

What this sandbox is
Settings files the sandbox could not read
Trade a sign-in for a session
The live event stream
Say what you are looking at
What has been spent
Open terminals
Close a terminal
A terminal's history as plain text
Browsers the agent has open
Shut a browser down
Helpers the agents have started
A helper agent's record
Drive a sandbox on one of your own computers

The group with the widest job. The identity read is what the daemon says it is, including the routes it implements, which is the one call that tells a newer client what this sandbox can do. The event stream is the sandbox-wide live feed. The rest is the machinery an agent leaves running: terminals and their history, browsers, and the records of helpers it delegated to.

14 calls. Pick one to open it, or use the list on the right.

GET/infoWhat this sandbox is

The sandbox's own identity and state: which workspace it holds, which image it runs, what it is called, and the list of calls it actually implements. Start here, because a browser is routinely newer than the sandbox it is talking to and this is how it finds out what is there.

What you send

Nothing. Call it as it is.

What comes back

Field	Type
`name`What this sandbox is called	string
`image`The image it is running	string
`version`The version of that image	string
`latest`The newest published version on its…	string
`updateAvailable`Whether those two differ	boolean
`runtimes`Which agent runtimes can serve a…	object
`channel`Which release channel this sandbox follows	string
`previousImage`The image the last update replaced,…	string
`updateNotes`What is in the update, in…	string[]
`moreUpdateNotes`How many further notes there are…	number
`breakingNotes`What the update takes away, uncapped,…	string[]
`staged`An update already downloaded and built…	object
`version`What the downloaded build says it…	string
`channel`Which channel it was taken from	string
`at`When the download finished, in milliseconds,…	number

Try itanswered in this tab

curl

curl "$SANDBOX/info" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.system.info();

GET/system/manifest-problemsSettings files the sandbox could not read

Anything the daemon tripped over in its own configuration on disk: a file it had to fall back from, a key it did not recognise, an entry it skipped. Separate from the identity call because it goes stale for a different reason, namely a file changing.

What you send

Nothing. Call it as it is.

What comes back

Field	Type
`path`The file, as a workspace path	string
`problems`Everything currently wrong with it	object[]
`kind`What to do about it	"unreadable" \| "unknownKey" \| "invalidEntry"
`detail`What exactly was wrong	string
`suggestion`The name it was probably meant…	string

Try itanswered in this tab

curl

curl "$SANDBOX/system/manifest-problems" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.system.manifestProblems();

POST/system/sessionTrade a sign-in for a session

Exchanges a verified sign-in, or a session that has not expired yet, for a fresh session the daemon minted. That session is the credential every other call carries, and calling this again with a live one renews it.

What you send

Nothing. Call it as it is.

What comes back

Field	Type
`token`The credential every other call carries	string
`expiresAt`When it stops working, in milliseconds,…	number
`email`Who the sandbox verified you as	string

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/system/session" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.system.session();

GET/eventsThe live event streamstream

A stream held open for as long as you want it, carrying heartbeats so a caller notices the sandbox dying at once, batches of file changes so a tree or an editor can refresh itself, and the roster of who else is looking. Give it an id for this connection to appear in that roster; leave it out and you watch without being seen.

What you send

Field	Type	Where
`clientId`	string	query

What comes back

Field	Type
`when event is "message"`	shape
`data`	object
`when kind is "hello"`	shape
`workspaceId`	string
`routes`	string[]
`shapes`	object
`build`	string
`boot`	object
`when kind is "heartbeat"`	shape
`when kind is "boot"`	shape
`ready`	boolean
`startedAt`	number
`steps`	object[]
`when kind is "workspaceChanged"`	shape
`paths`	string[]
`when kind is "reposChanged"`	shape
`repos`	string[]
`when kind is "refsChanged"`	shape
`repos`	string[]
`when kind is "runtimeChanged"`	shape
`domains`	string[]
`when kind is "presence"`	shape
`users`	object[]
`when kind is "agents"`	shape
`agents`	object[]
`rev`	number
`id`	string
`retry`	number
`when event is "done"`	shape
`data`	unknown
`id`	string
`retry`	number
`when event is "error"`	shape
`data`	unknown
`id`	string
`retry`	number

Try itanswered in this tab

curl

curl -N "$SANDBOX/events" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.system.events();

POST/system/presenceSay what you are looking at

Reports which view, conversation or file this connection is on, or that it has gone idle. The daemon fans it back out on the event stream so everyone else's roster updates.

What you send

Field	Type	Where
`clientId`requiredThis connection's own id, the same…	string	body
`idle`requiredWhether the person has stopped doing…	boolean	body
`view`Which view they are on	string	body
`sessionId`Which conversation they have open	string	body
`path`Which file they are looking at	string	body

What comes back

Field	Type
`ok`Always true	true

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/system/presence" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"clientId":"a1b2c3d4","idle":true,"view":"…","sessionId":"a1b2c3d4","path":"src/app.ts"}'

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.system.presence({
  "clientId": "a1b2c3d4",
  "idle": true,
  "view": "…",
  "sessionId": "a1b2c3d4",
  "path": "src/app.ts"
});

GET/system/usageWhat has been spent

Token and cost totals per account, added up from the record of every finished turn.

What you send

Nothing. Call it as it is.

What comes back

Field	Type
`accounts`	object[]
`provider`	string
`account`	string
`turns`	number
`inputTokens`	number
`outputTokens`	number
`cacheReadTokens`	number
`cacheCreationTokens`	number
`costUsd`	number

Try itanswered in this tab

curl

curl "$SANDBOX/system/usage" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.system.usage();

GET/system/terminalsOpen terminals

The terminal sessions this sandbox is holding, which is what a terminal panel rebuilds its tabs from after a reload. The live typing and output run over a separate socket; this is the list.

What you send

Nothing. Call it as it is.

What comes back

Field	Type
`sessions`Every live surface the sandbox is…	object[]
`name`Its id, and what the close…	string
`label`What to call it on screen	string
`kind`What sort of thing it is:…	"shell" \| "panel" \| "agent" \| "job" … (5)
`running`Whether it is alive	boolean
`activityAt`When it last produced output, in…	number
`exitCode`How the last thing in it…	number
`command`What is running in it right…	string
`extensionId`Which extension declared this process, when…	string
`processName`Which of that extension's processes it…	string
`help`The agent has stopped at something…	object
`requestId`What to send back when you…	string
`message`What the agent needs, in its…	string
`requestedAt`When it asked, in milliseconds	number

Try itanswered in this tab

curl

curl "$SANDBOX/system/terminals" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.system.terminals();

DELETE/system/terminals/{name}Close a terminal

Destroys one terminal session and whatever was running inside it.

What you send

Field	Type	Where
`name`requiredWhich terminal	string	address

What comes back

Field	Type
`ok`Always true	true

Try itanswered in this tab

curl

curl -X DELETE "$SANDBOX/system/terminals/nightly%20changelog" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.system.killTerminal({
  "name": "nightly changelog"
});

GET/system/terminals/{name}/scrollbackA terminal's history as plain text

What has scrolled past in one terminal, as text you can select and copy. The live view is a picture of a screen on the far side of a socket, with nothing in the page to select, so scrolling back and copying is this call rather than a gesture.

What you send

Field	Type	Where
`name`requiredWhich terminal	string	address
`lines`How far back to ask for	number	query

What comes back

Field	Type
`name`Which terminal this is from	string
`text`The history, oldest line first, with…	string
`lines`How many lines you got	number
`truncated`It stopped because you asked for…	boolean

Try itanswered in this tab

curl

curl "$SANDBOX/system/terminals/nightly%20changelog/scrollback" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.system.terminalScrollback({
  "name": "nightly changelog"
});

GET/system/browsersBrowsers the agent has open

Every browser a conversation currently has running and the pages inside each one. The picture of what they are showing comes over a separate socket; this is the roster.

What you send

Nothing. Call it as it is.

What comes back

Field	Type
`sessions`Every browser the agents have running,…	object[]
`name`Its id, and what the close…	string
`label`What to call it on screen:…	string
`server`Which browser drives it: the credential-free…	string
`running`Whether it is still open	boolean
`activityAt`When it last did anything, in…	number
`finishedAt`When it closed, in milliseconds	number
`help`The agent has hit something only…	object
`requestId`What to send back when you…	string
`message`What the agent needs, in its…	string
`requestedAt`When it asked, in milliseconds	number
`pages`Every page it has open	object[]
`id`Stable for the life of the…	string
`title`The page's title	string
`url`Where it is	string
`active`The one the agent last touched,…	boolean

Try itanswered in this tab

curl

curl "$SANDBOX/system/browsers" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.system.browsers();

DELETE/system/browsers/{name}Shut a browser down

Closes one of the agent's browsers. Its next attempt to use that browser then fails as though it had crashed, which is the honest account of somebody pulling the plug.

What you send

Field	Type	Where
`name`requiredWhich browser	string	address

What comes back

Field	Type
`ok`Always true	true

Try itanswered in this tab

curl

curl -X DELETE "$SANDBOX/system/browsers/nightly%20changelog" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.system.closeBrowser({
  "name": "nightly changelog"
});

GET/system/subagentsHelpers the agents have started

Every helper agent this sandbox's conversations have delegated work to, whichever tool started it, with what each one is doing.

What you send

Nothing. Call it as it is.

What comes back

Field	Type
`sessions`Every helper this sandbox's conversations have…	object[]
`id`The id of the tool call…	string
`kind`What sort of helper: one the…	"subagent" \| "codex" \| "grok"
`conversationId`The conversation whose turn started it,…	string
`agentType`What kind of helper it is	string
`description`What it was asked to do,…	string
`model`Which model it runs on	string
`spawnDepth`How deep in the chain it…	number
`background`The parent carried on working instead…	boolean
`status`How it is going	"pending" \| "running" \| "blocked" \| "completed" … (7)
`startedAt`When it started, in milliseconds	number
`endedAt`When it finished, in milliseconds	number
`activityAt`When it last did anything, in…	number
`tokens`What it has spent	number
`toolUses`How many tools it has used	number
`lastTool`The last one it reached for	string
`summary`Its report: what it concluded, without…	string
`error`Why it failed, when it did	string
`terminal`The terminal its command runs in,…	string

Try itanswered in this tab

curl

curl "$SANDBOX/system/subagents" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.system.subagents();

GET/system/subagents/{id}/transcriptA helper agent's record

The full record of one delegated helper, in the same shape as any other conversation. It comes live from the parent turn while the helper works, and from stored history once it has finished.

What you send

Field	Type	Where
`id`required	string	address

What comes back

Field	Type
`messages`The conversation, in order	object[]
`role`Who said it	"user" \| "assistant" \| "notice"
`text`The words	string
`sentAt`When it was sent, in milliseconds	number
`attachments`Files attached to this message, as…	string[]
`checkpointId`The saved point this message can…	string
`thinking`What the agent was reasoning about	string
`tools`The tool calls this part of…	object[]
`id`The call's id	string
`name`Which tool	string
`category`What kind of thing it does:…	"read" \| "edit" \| "delete" \| "move" … (9)
`status`How it went	"pending" \| "in_progress" \| "completed" \| "failed"
`target`What it acted on, in one…	string
`locations`The files it touched	object[]
`path`The file, as a workspace path,…	string
`line`Which line, counting from one	number
`content`What it produced: text, a change…	object[]
`type`Plain output	"text"
`text`What the tool said	string
`children`Calls a delegated helper made, nested…	object[]
`id`The call's id	string
`name`Which tool	string
`category`What kind of thing it does:…	"read" \| "edit" \| "delete" \| "move" … (9)
`status`How it went	"pending" \| "in_progress" \| "completed" \| "failed"
`target`What it acted on, in one…	string
`locations`The files it touched	object[]
`content`What it produced: text, a change…	object[]
`children`Calls a delegated helper made, nested…	object[]
`thinking`What the agent was reasoning about…	string
`thinking`What the agent was reasoning about…	string
`notes`What the sandbox added to this…	object[]
`title`The one line a reader sees,…	string
`text`The note itself, which is also…	string
`placed`A person wrote this in the…	boolean
`noticeAction`A one-press follow-up this recorded notice…	"tierHold"

Try itanswered in this tab

curl

curl "$SANDBOX/system/subagents/a1b2c3d4/transcript" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.system.subagentTranscript({
  "id": "a1b2c3d4"
});

POST/system/computers/{id}/sandboxes/{slug}Drive a sandbox on one of your own computersstream

Start, stop, restart, update, rebuild, roll back or remove a sandbox running on a machine you own, relayed over the connection that machine holds open. The answer is a stream because the slowest of these takes minutes, and it is the same stream whichever you ask for. The daemon adds no opinion: the machine enforces its own permissions and a refusal arrives as the last line, in the machine's words, naming the switch to flip.

What you send

Field	Type	Where
`id`required	string	address
`slug`required	string	address
`op`required	"start" \| "stop" \| "restart" \| "prepare" … (9)	body
`hash`	string	body

What comes back

Field	Type
`when event is "message"`	shape
`data`	object
`when kind is "line"`	shape
`text`	string
`when kind is "result"`	shape
`message`	string
`when kind is "error"`	shape
`message`	string
`id`	string
`retry`	number
`when event is "done"`	shape
`data`	unknown
`id`	string
`retry`	number
`when event is "error"`	shape
`data`	unknown
`id`	string
`retry`	number

Try itanswered in this tab

curl

curl -N -X POST "$SANDBOX/system/computers/a1b2c3d4/sandboxes/nightly-changelog" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"op":"start","hash":"…"}'

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.system.manageMachineSandbox({
  "id": "a1b2c3d4",
  "slug": "nightly-changelog",
  "op": "start",
  "hash": "…"
});