The sandbox itself

System

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

On this page(25 sections)

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.

25 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
`plan`What the downloaded build's first boot…	object
`plan`The format of this line	1
`version`The release of the image that…	string
`engine`The conversion count builds before the…	number
`digest`What identifies the planning build's conversion…	string
`ok`False when a conversion would fail…	boolean
`downgrade`A newer release than the planning…	boolean
`failures`Each conversion or step that would…	object[]
`document`The stored file whose conversion would…	string
`detail`Why, in the conversion's own words	string
`steps`What the first boot changes on…	object[]
`document`The stored file, workspace-relative, or `<volume>:<path>`…	string
`change`What is done to it, in…	string
`detail`What was particular about this one:…	string
`converts`What the build's conversions change as…	object[]
`document`The stored file, workspace-relative, or `<volume>:<path>`…	string
`change`What is done to it, in…	string
`detail`What was particular about this one:…	string
`files`Every file the first boot writes,…	string[]
`preparing`A download of the next update…	object
`channel`Which channel it is being taken…	string
`startedAt`When the download began, in milliseconds	number
`at`When the machine last said it…	number
`phase`What it is doing: download (pulling…	string
`percent`How far through the download it…	number
`lastUpdate`What the machine running this sandbox…	object
`result`What happened	"updated" \| "kept" \| "restored" \| "rolled-back"
`verb`What was asked for: update, rollback,…	string
`at`When it happened, in milliseconds	number
`from`The version (or, when it would…	string
`to`The version (or image) that was…	string
`reason`Why the host gave up on…	string
`log`Where the host kept the full…	string
`keepUntil`Until when the previous version stays…	number
`withdrawn`Set when the version this sandbox…	object
`version`The withdrawn version, which is the…	string
`reason`Why it was withdrawn, as the…	string
`skippedVersion`A release the owner chose to…	string
`autoUpdate`Whether and when this sandbox takes…	object
`enabled`Whether this sandbox takes downloaded updates…	boolean
`phase`Where it stands: idle (nothing downloaded…	string
`version`The downloaded version it will take	string
`holds`Everything keeping it waiting right now,…	object[]
`kind`What it waits on: agents (an…	string
`names`Who or what, by name: the…	string[]
`until`When this lifts by itself, in…	number
`startsAt`During a countdown, when the restart…	number
`pausedUntil`The owner's pause: no automatic update…	number
`failure`Why the last automatic try did…	string
`lastApplied`The last update this sandbox took…	object
`at`	number
`to`	string

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();

POST/system/update/skipStop offering one release

Stops offering the named release as an update, typically one this sandbox already tried and went back from. A newer release is offered as usual. Null offers the newest release again.

What you send

Field	Type	Where
`version`requiredThe release to stop offering, or…	string \| null	body

What comes back

Field	Type
`ok`Always true	true

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/system/update/skip" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"version":"1.4.0"}'

TypeScript

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

const result = await sandbox.system.skipUpdate({
  "version": "1.4.0"
});

POST/system/update/autoDecide how updates are taken

Turns taking a downloaded update by itself on or off, pauses it until a moment, or takes the downloaded update right now. A sandbox taking updates by itself waits for a quiet moment: no agent mid-turn, nobody at the editor, terminals quiet. Answers with where it stands afterwards.

What you send

Field	Type	Where
`enabled`Turn taking downloaded updates by itself…	boolean	body
`pausedUntil`Hold automatic updates until this moment,…	number	body
`applyNow`Take the downloaded update now, without…	true	body

What comes back

Field	Type
`enabled`Whether this sandbox takes downloaded updates…	boolean
`phase`Where it stands: idle (nothing downloaded…	string
`version`The downloaded version it will take	string
`holds`Everything keeping it waiting right now,…	object[]
`kind`What it waits on: agents (an…	string
`names`Who or what, by name: the…	string[]
`until`When this lifts by itself, in…	number
`startsAt`During a countdown, when the restart…	number
`pausedUntil`The owner's pause: no automatic update…	number
`failure`Why the last automatic try did…	string
`lastApplied`The last update this sandbox took…	object
`at`	number
`to`	string

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/system/update/auto" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"enabled":true,"pausedUntil":1,"applyNow":true}'

TypeScript

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

const result = await sandbox.system.autoUpdate({
  "enabled": true,
  "pausedUntil": 1,
  "applyNow": true
});

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"
`reason`Why it could not be read:…	"io" \| "not-json" \| "conversion-failed" \| "rejected"
`detail`What exactly was wrong, as one…	string
`suggestion`The name it was probably meant…	string
`fix`What to do about it, when…	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/manifest-problems/repairTake a stray setting out of a file

Removes a key the sandbox does not recognise from one of its settings files, or renames it to the one it was probably meant to be, keeping the value. Only the files a person hand-edits can be named, and only a key — never a value — so this can only ever remove something already being ignored. Renaming onto a key the file already has is refused instead of overwriting it.

What you send

Field	Type	Where
`path`requiredThe file to repair, as the…	string	body
`key`requiredThe stray top-level key, exactly as…	string	body
`to`Rename the key to this instead…	string	body

What comes back

Field	Type
`ok`Always true	true

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/system/manifest-problems/repair" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"path":"src/app.ts","key":"OPENAI_API_KEY","to":"src/server.ts"}'

TypeScript

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

const result = await sandbox.system.repairManifest({
  "path": "src/app.ts",
  "key": "OPENAI_API_KEY",
  "to": "src/server.ts"
});

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
`projectDir`	string
`surface`	"sandbox" \| "folder"
`when kind is "heartbeat"`	shape
`rev`	number
`when kind is "boot"`	shape
`ready`	boolean
`startedAt`	number
`steps`	object[]
`when kind is "workspaceChanged"`	shape
`paths`	string[]
`when kind is "treeChanged"`	shape
`from`The generation this applies on top…	integer
`generation`The generation it leaves the tree…	integer
`dirs`Each folder that changed, parents before…	object[]
`barren`The barren folders now, present only…	string[]
`when kind is "derivedChanged"`	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
`when kind is "accountUsage"`	shape
`provider`	string
`account`	string
`usage`	object
`when kind is "providerRefusal"`	shape
`provider`	string
`refusal`	object
`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
`away`Whether the window is on screen…	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,"away":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,
  "away": 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/metricsWhat the sandbox is using right now

CPU and memory for the sandbox as a whole, for the daemon that runs it, for each kind of process, and for each conversation's own processes. Measured when you ask and never in between, so CPU is the use since the previous reading: the first reading after a quiet spell has memory and no CPU, and the next one a few seconds later has both.

What you send

Nothing. Call it as it is.

What comes back

Field	Type
`at`When this reading was taken, in…	number
`windowMs`How long the CPU figures were…	number
`sandbox`The sandbox as a whole	object
`cpuPercent`CPU the whole sandbox used over…	number
`cores`How many cores the sandbox may…	number
`memoryBytes`Memory counted against the limit, as…	number
`memoryLimitBytes`The memory limit work is admitted…	number
`swapBytes`What was pushed out to swap,…	number
`swapLimitBytes`What swap can hold	number
`swapFull`Swap is nearly at `swapLimitBytes`: nothing…	boolean
`memoryRoom`What admission reads off the same…	object
`freeBytes`The limit less what is used…	number
`reservedBytes`What work admitted in the last…	number
`personNeedBytes`What a person's turn needs free…	number
`stallPercent`Percent of the last ten seconds…	number
`stallLimitPercent`The stall at or past which…	number
`stallSustainedPercent`Percent of the last minute in…	number
`stallSustainedLimitPercent`The minute's stall at or past…	number
`diskBytes`Space used on the volume the…	number
`diskTotalBytes`That volume's size	number
`loadAverage`The load average over 1, 5…	unknown[]
`machineCores`Cores the machine's load average reads…	number
`processes`How many processes are running in…	number
`pressure`How much work waited on CPU,…	object
`cpu`Percent of the last ten seconds…	number
`memory`Percent of the last ten seconds…	number
`io`Percent of the last ten seconds…	number
`daemon`The daemon that runs it, which…	object
`rssBytes`The daemon's own resident memory	number
`heapUsedBytes`Of that, JavaScript objects in use	number
`cpuPercent`CPU the daemon itself used over…	number
`eventLoopPercent`How much of the window the…	number
`sessions`What each conversation's processes use, by…	object
`roles`Every process in the sandbox but…	object

Try itanswered in this tab

curl

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

TypeScript

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

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

GET/system/storageWhat is filling the disk

The last measurement of the sandbox's disk, by what the space is for: conversations, checkouts, restore points, caches, logs, the trash and the rest, each with its biggest parts and whether it can be cleaned from here. Reading it measures nothing; ask for a scan to measure again.

What you send

Nothing. Call it as it is.

What comes back

Field	Type
`scan`The last scan that finished	object
`startedAt`When the scan began, in milliseconds	number
`finishedAt`When it ended, in milliseconds: the…	number
`outcome``partial` when the scan hit its…	"complete" \| "partial"
`disk`The volume as a whole	object
`usedBytes`Space used on the volume the…	number
`totalBytes`That volume's size	number
`categories`Every category that holds anything, largest…	object[]
`id`	"workspace" \| "conversations" \| "checkouts" \| "restorePoints" … (22)
`cleanability`Whether this category can be cleaned…	"none" \| "safe" \| "confirm"
`bytes`Its size in bytes	number
`files`How many files it holds	number
`cleanableBytes`What cleaning it would free right…	number
`items`Its biggest parts, largest first, at…	object[]
`path`Where it is, as an absolute…	string
`bytes`Its size in bytes	number
`unreadable`Files and folders the scan could…	number
`scanning`Whether a scan is running now	boolean

Try itanswered in this tab

curl

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

TypeScript

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

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

POST/system/storage/scanMeasure what is filling the disk

Walks the sandbox's volumes and answers with the new measurement once it is done. A scan already running is joined rather than doubled. It stops at a time limit and says so, since a size it could not finish is still worth reading. A cancelled scan answers with the previous measurement.

What you send

Nothing. Call it as it is.

What comes back

Field	Type
`scan`The last scan that finished	object
`startedAt`When the scan began, in milliseconds	number
`finishedAt`When it ended, in milliseconds: the…	number
`outcome``partial` when the scan hit its…	"complete" \| "partial"
`disk`The volume as a whole	object
`usedBytes`Space used on the volume the…	number
`totalBytes`That volume's size	number
`categories`Every category that holds anything, largest…	object[]
`id`	"workspace" \| "conversations" \| "checkouts" \| "restorePoints" … (22)
`cleanability`Whether this category can be cleaned…	"none" \| "safe" \| "confirm"
`bytes`Its size in bytes	number
`files`How many files it holds	number
`cleanableBytes`What cleaning it would free right…	number
`items`Its biggest parts, largest first, at…	object[]
`path`Where it is, as an absolute…	string
`bytes`Its size in bytes	number
`unreadable`Files and folders the scan could…	number
`scanning`Whether a scan is running now	boolean

Try itanswered in this tab

curl

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

TypeScript

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

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

DELETE/system/storage/scanStop measuring the disk

Stops a running scan. Whoever was waiting on it gets the previous measurement back; nothing is lost but the time.

What you send

Nothing. Call it as it is.

What comes back

Field	Type
`ok`Always true	true

Try itanswered in this tab

curl

curl -X DELETE "$SANDBOX/system/storage/scan" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

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

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

POST/system/storage/cleanFree the space one category holds

Removes what one cleanable category holds, and says how much space that gave back. Only what is old enough and not in use goes: today's logs, a browser that is open, the weights a running model reads and a pack still being written all stay. Nothing outside the sandbox's own volumes, and nothing a category may not hold, is ever removed. Categories that cannot be cleaned are refused.

What you send

Field	Type	Where
`category`requiredThe category to clean; one whose…	"workspace" \| "conversations" \| "checkouts" \| "restorePoints" … (22)	body

What comes back

Field	Type
`category`	"workspace" \| "conversations" \| "checkouts" \| "restorePoints" … (22)
`freedBytes`Space the removals gave back, in…	number
`removed`How many items were removed	number
`kept`How many were left in place:…	number
`failed`How many removals the filesystem refused	number

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/system/storage/clean" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"category":"workspace"}'

TypeScript

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

const result = await sandbox.system.cleanStorage({
  "category": "workspace"
});

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
`dialog`A dialog a page has open…	object
`pageId`Which page opened it	string
`kind`What it asks: an alert wants…	"alert" \| "confirm" \| "prompt" \| "beforeunload"
`message`What the page says	string
`defaultValue`A prompt's prefilled answer	string
`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/desktopThe sandbox's own desktop

Whether the sandbox's desktop is up, which display it is, and how many windows are open on it. The live picture of it comes over a separate socket; this says whether there is anything to see.

What you send

Nothing. Call it as it is.

What comes back

Field	Type
`running`Whether the desktop is up	boolean
`display`The X display it is, present…	string
`windows`How many windows are open on…	integer

Try itanswered in this tab

curl

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

TypeScript

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

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

GET/system/subagentsSubagents the agents have started

Every subagent that conversations the caller can see have delegated work to, whichever tool started it, with what each one is doing: all that are still working, and the most recent that have settled.

What you send

Nothing. Call it as it is.

What comes back

Field	Type
`sessions`The subagents conversations the caller can…	object[]
`id`The id of the tool call…	string
`kind`How it was started: in-process by…	"subagent" \| "spawned"
`conversationId`The conversation whose turn started it,…	string
`agentType`What kind of subagent it is	string
`description`What it was asked to do,…	string
`model`Which model it runs on: the…	string
`effort`How hard it was told to…	string
`provider`Which provider serves it, for a…	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
`verification`Whether anything proved the work its…	object
`state`Whether anything proved its work: a…	"verified" \| "unproven" \| "failing" \| "no-code"
`paths`The code files it changed, most…	string[]
`check`The command that spoke: the one…	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/devicesThe machines you have connected

Every computer this sandbox can see, whether it reached it through desktop sync or through a connected device, in one row per machine: what it says about itself, which sandboxes it holds, and what stopped it answering when nothing came back.

What you send

Nothing. Call it as it is.

What comes back

Field	Type
`devices`	object[]
`key`	string
`label`	string
`sync`	object
`machine`	string
`mode`	"sync" \| "mirror"
`seenAt`	number
`machineId`	string
`environment`	string
`hostId`	string
`card`	string
`machineId`	string
`online`	boolean
`platform`	string
`facts`	object
`machineId`	string
`os`	string
`arch`	string
`shell`	string
`home`	string
`roots`	string[]
`engine`	object
`memoryBytes`	number
`cpus`	number
`hostname`	string
`wsl`	object
`distro`	string
`wslDistros`	string[]
`links`	object
`total`	number
`unreachable`	number
`unreachableSince`	number
`features`	string[]
`icOutOfDate`	string
`upkeep`	object
`at`	number
`found`	object
`fixed`	object
`skipped`	object[]
`agentVersion`	string
`lastSeen`	number
`report`	object
`machineId`	string
`hostname`	string
`os`	string
`wsl`	object
`distro`	string
`pairings`	object[]
`sandboxId`	string
`mode`	"sync" \| "mirror"
`localDir`	string
`remoteDir`	string
`projectsHost`	boolean
`deliver`	"auto" \| "off"
`mirroring`	"on" \| "off"
`mutagenStatus`	string
`conflicts`	integer
`conflictedPaths`	object[]
`paused`	boolean
`backupStatus`	string
`ports`	object[]
`port`	integer
`host`	"127.0.0.1" \| "::1"
`sandboxId`	string
`state`	"mirrored" \| "held-by-sandbox" \| "busy" \| "ignored"
`heldBy`	string
`command`	string
`agent`	object
`running`	boolean
`pid`	integer
`installed`	string
`build`	string
`lastTickAt`	number
`capturedAt`	number
`sandboxes`	object[]
`slug`	string
`container`	string
`name`	string
`running`	boolean
`image`	string
`tunnelRunning`	boolean
`resources`	object
`memoryBytes`	number
`cpus`	number
`privileged`	boolean
`gpu`	boolean
`hostRuntime`	string[]
`overlayRuntime`	string[]
`shape`	object
`desired`	object
`saved`	object
`staged`	object
`image`	string
`version`	string
`channel`	string
`version`	string
`parked`	boolean
`probationUntil`	number
`lastUpdate`	object
`result`What happened	"updated" \| "kept" \| "restored" \| "rolled-back"
`verb`What was asked for: update, rollback,…	string
`at`When it happened, in milliseconds	number
`from`The version (or, when it would…	string
`to`The version (or image) that was…	string
`reason`Why the host gave up on…	string
`log`Where the host kept the full…	string
`keepUntil`Until when the previous version stays…	number
`rollbackTargets`	object[]
`image`The local image a rollback would…	string
`version`What that image says it is	string
`download`The local pin is gone (pruned…	boolean
`keptElsewhere`	string
`keptElsewhereName`	string
`adoptedFrom`	string
`keeperSilentSince`	number
`gap`	"offline" \| "scope-off" \| "unreported"

Try itanswered in this tab

curl

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

TypeScript

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

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

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

Start, stop, restart, update, rebuild, roll back, reshape (its memory and CPU caps, privileged, GPU) 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" … (17)	body
`hash`	string	body
`to`	string	body
`shape`	object	body
`memoryGib`required	integer \| null	body
`cpus`required	integer \| null	body
`privileged`required	boolean	body
`gpu`required	boolean	body
`when`	"now" \| "nextRestart"	body
`resources`	object	body
`memoryGib`	integer \| null	body
`cpus`	integer \| null	body
`privileged`	boolean	body
`gpu`	boolean	body
`later`	boolean	body
`parentUrl`	string	body
`pair`	string	body
`setupCode`	string	body
`platformUrl`	string	body
`definition`	string	body
`overlay`	string	body
`overlayHash`	string	body
`resumeTurns`	boolean	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/devices/a1b2c3d4/sandboxes/nightly-changelog" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"op":"start","hash":"…","to":"src/server.ts","shape":{"memoryGib":1,"cpus":1,"privileged":true,"gpu":true},"when":"now","resources":{"memoryGib":1,"cpus":1,"privileged":true,"gpu":true},"later":true,"parentUrl":"https://sandbox-a1b2c3d4e5f6.intentic.dev","pair":"…","setupCode":"…","platformUrl":"https://sandbox-a1b2c3d4e5f6.intentic.dev","definition":"…","overlay":"…","overlayHash":"…","resumeTurns":true}'

TypeScript

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

const result = await sandbox.system.manageDeviceSandbox({
  "id": "a1b2c3d4",
  "slug": "nightly-changelog",
  "op": "start",
  "hash": "…",
  "to": "src/server.ts",
  "shape": {
    "memoryGib": 1,
    "cpus": 1,
    "privileged": true,
    "gpu": true
  },
  "when": "now",
  "resources": {
    "memoryGib": 1,
    "cpus": 1,
    "privileged": true,
    "gpu": true
  },
  "later": true,
  "parentUrl": "https://sandbox-a1b2c3d4e5f6.intentic.dev",
  "pair": "…",
  "setupCode": "…",
  "platformUrl": "https://sandbox-a1b2c3d4e5f6.intentic.dev",
  "definition": "…",
  "overlay": "…",
  "overlayHash": "…",
  "resumeTurns": true
});

POST/system/devices/{id}/commands/{command}Run one of your device's own CLI actions

Performs a named action on a machine you own by running its own intentic-machine command there — turning that device's port mirroring off, say — over the connection it holds open. The set of actions is fixed and the command line is built here from the name, never sent by the caller. The machine enforces its own permissions and a refusal comes back as its own sentence, naming the switch to flip.

What you send

Field	Type	Where
`id`required	string	address
`command`required	"mirror-off" \| "mirror-on" \| "mirror-ignore" \| "mirror-unignore" … (12)	address
`sandboxId`	string	body
`mode`	"sync" \| "mirror"	body
`localDir`	string	body
`port`	integer	body

What comes back

Field	Type
`ok`	boolean
`message`	string
`output`	string
`refused`	boolean

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/system/devices/a1b2c3d4/commands/mirror-off" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"sandboxId":"a1b2c3d4e5f6","mode":"sync","localDir":"…","port":5173}'

TypeScript

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

const result = await sandbox.system.runDeviceCommand({
  "id": "a1b2c3d4",
  "command": "mirror-off",
  "sandboxId": "a1b2c3d4e5f6",
  "mode": "sync",
  "localDir": "…",
  "port": 5173
});

POST/system/devices/{id}/agent/{op}Update, restart, or clean up the links of the agent on one of your own devicesstream

Updates a machine you own to the current intentic-machine agent, restarts the loop it is running, or drops the links it holds to sandboxes that have stopped answering — over the connection that machine holds open. The answer is a stream of the run's own output — and it normally stops mid-run, because the agent's loop is what carries this connection: the work is detached from it first, so it finishes regardless, and the device's reported version is what confirms it. Takes the machine's "Run commands" permission, the same one a command typed there would.

What you send

Field	Type	Where
`id`required	string	address
`op`required	"upgrade" \| "restart" \| "forget-unreachable"	address

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/devices/a1b2c3d4/agent/upgrade" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

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

const result = await sandbox.system.runDeviceAgentFlow({
  "id": "a1b2c3d4",
  "op": "upgrade"
});