Sandboxes

Reading the Linux instances an agent was granted, and cleaning up the archive one leaves behind.

An agent’s config can grant it sandboxes: Linux instances the session owns, each served to the model at sandbox:{name} with an exec tool. The SDK does not start or stop them — the grant does that — but it reads what they are doing and manages the archive a retired one leaves behind.

Added in 0.1.1.

Listing them

const { items } = await subako.sessions.listSandboxes(sessionId);

for (const sandbox of items) {
	console.log(sandbox.name, sandbox.status, sandbox.archive_bytes);
}

This is the one listing that does not answer with a Page, and its type says so. A grant list is written into the agent’s config, so the set is bounded and the whole of it travels at once: { items }, no cursor, nothing to follow.

PropType

namestring

The label the agent's config invented. The model reaches this sandbox at `sandbox:{name}`.

Typestring

Where the instance is in its life. A sandbox idles into `suspended` and retires into `archived`.

environmentSessionSandboxEnvironmentBody

Which image it boots.

TypeSessionSandboxEnvironmentBody

networkSessionSandboxNetworkBody

Where it may reach, as its grant said when the session was made.

TypeSessionSandboxNetworkBody

classstring

The machine class it runs on.

Typestring

created_atstring

When the sandbox was made.

Typestring

last_used_at?string | null

When it last ran something.

Typestring | null

archive_bytes?number | null

Size of the last published snapshot, which can predate the latest exec.

Typenumber | null

archive_refused_bytes?number | null

What the workspace packed to when a backup was last refused for size.

Typenumber | null

The archive

A retired sandbox publishes a snapshot. Reading it answers with a presigned download that lapses:

const archive = await subako.sessions.getSandboxArchive(sessionId, "build");

archive.url; // fetch it before it expires
archive.bytes;
archive.expires_at;

An archive that is no longer worth keeping is deleted by name, which stops the storage it is billed for:

await subako.sessions.deleteSandboxArchive(sessionId, "build");

A sandbox with no published archive answers 404 — NotFoundError.

A delete answers 409 — ConflictError — while the sandbox is provisioning, running, draining, or suspended. Retirement is automatic, so wait for the status to reach archived or failed and ask again; the SDK does not retry a 409, and would have nothing to gain by it. Idling only suspends an instance — retirement follows the configured suspended duration or the instance lifetime — and a concurrent exec can restart it before the deletion lands.

Reachable from either client

All three sit on the half both clients bind, so a browser holding a session token reaches them exactly as a backend does:

await subako.listSandboxes(sessionId); // SubakoSessionClient
await subako.sessions.listSandboxes(sessionId); // SubakoClient