SandboxSession
One live sandbox, as an adapter returns it from create, restore or attach: run commands, move files, snapshot and close it, and, with the optional Trees capability, export and import /workspace as a tar archive.
Every method takes the SandboxContext to fence at the provider call.
Properties
idstringrequiredBranded SandboxId.
Methods
exec
A timeout kills the whole process group.
exec(command: readonly string[], context: SandboxContext, options: {
cwd?: string;
env?: Record<string, string>;
timeoutMs?: PosInt;
stdin?: Uint8Array;
processKey: string;
}): Promise<Result<ExecOutput>>commandreadonly string[]requiredThe program and its arguments, run directly as argv, not as a shell string. Pass ["/bin/sh", "-c", script] to use a shell. An empty command is a caller bug: exec throws (Python ValueError) before anything reaches the sandbox.
contextSandboxContextrequiredThe authority to re-check with context.fence() before starting the process. See SandboxContext.
cwdstringdefault /workspaceThe absolute working directory inside the sandbox. A path outside the sandbox tree is invalid_path.
envRecord<string, string>default {}Exactly this env; nothing inherited. Each name is a shell variable name ([A-Za-z_][A-Za-z0-9_]*) and must not start with _t, which the sandbox-side wrapper keeps for itself; any other name is a caller bug: exec throws (Python ValueError) before anything is sent.
timeoutMs / timeout_msPosIntDeadline in milliseconds. The framework's sandbox layer enforces it: once it passes, the call ends as timeout and the process group is terminated. When omitted, the command has no time limit.
stdinUint8ArrayBytes fed to the process's standard input. When omitted, standard input is empty (/dev/null).
processKey / process_keystringrequiredDurable identity of the process group: the call's effect key, recorded by effect_begin before dispatch, so recovery can terminate it after a crash.
Returns an error value with one of these codes: stale_epoch, cleanup_claim_lost, timeout, invalid_path, unavailable.
terminate
Kill the process group started with this process_key and confirm it is gone. terminated or already_exited → tool_result{origin: interrupted}. unknown or an error → the effect parks. Always unknown when info.termination is unconfirmed.
terminate(processKey: string, context: SandboxContext): Promise<Result<"terminated" | "already_exited" | "unknown">>processKey / process_keystringrequiredThe process_key the process group was started with in exec.
contextSandboxContextrequiredThe authority to re-check with context.fence() before the kill. See SandboxContext.
Returns an error value with one of these codes: stale_epoch, cleanup_claim_lost, unavailable.
upload
Write bytes to a file in the sandbox, creating or replacing it.
upload(path: string, data: Uint8Array, context: SandboxContext): Promise<Result<void>>pathstringrequiredThe absolute file path inside the sandbox. A path outside the sandbox tree is invalid_path.
dataUint8ArrayrequiredThe file's complete contents.
contextSandboxContextrequiredThe authority to re-check with context.fence() before writing. See SandboxContext.
Returns an error value with one of these codes: stale_epoch, cleanup_claim_lost, invalid_path, permission_denied, is_directory, too_large, unavailable.
download
Read a file's bytes from the sandbox.
download(path: string, context: SandboxContext): Promise<Result<Uint8Array>>pathstringrequiredThe absolute file path inside the sandbox. A missing file is not_found; a path outside the sandbox tree is invalid_path.
contextSandboxContextrequiredThe authority to re-check with context.fence() before reading. See SandboxContext.
Returns an error value with one of these codes: stale_epoch, cleanup_claim_lost, not_found, invalid_path, permission_denied, is_directory, too_large, unavailable.
snapshot
Freeze or stop tracked processes, capture, thaw. Returns only once durable and restorable.
snapshot(operationKey: string, context: SandboxContext): Promise<Result<SnapshotEvent.data>>operationKey / operation_keystringrequiredThe key the runtime wrote to the resource ledger before this call. Tag the snapshot with it so lookupSnapshot can find it if the response is lost.
contextSandboxContextrequiredThe authority to re-check with context.fence() before capturing. See SandboxContext.
Returns an error value with one of these codes: stale_epoch, cleanup_claim_lost, not_quiescent, unavailable, timeout.
close
Release the sandbox (ledger row releasing). ok → released. An error → release_failed, retried by the next gc, never dropped.
close(context: SandboxContext): Promise<Result<void>>contextSandboxContextrequiredThe authority to re-check with context.fence() before releasing: the owner's lease, or gc's cleanup claim. See SandboxContext.
Returns an error value with one of these codes: stale_epoch, cleanup_claim_lost, release_failed, unavailable.
exportTree / export_tree
Stream /workspace as a tar archive: the archive on stdout, then exit_code 0; any other exit code means the export failed, and stderr says why. The archive is a sandbox response: the runtime parses it strictly before using it. Setuid, setgid and sticky bits are reported as the sandbox has them.
exportTree(context: SandboxContext): Promise<Result<ExecOutput>>contextSandboxContextrequiredThe authority to re-check with context.fence() at every provider request the export makes. See SandboxContext.
Returns an error value with one of these codes: stale_epoch, cleanup_claim_lost, unavailable.
importTree / import_tree
Extract a host-built tar archive into /workspace, keeping each entry's mode as the archive gives it but never its owner. The runtime's tree builder writes every mode as mode & 0o777, so setuid, setgid and sticky bits never survive an import (a sandbox extracting as root would keep them). Existing files at the archive's paths are replaced.
importTree(tar: AsyncIterable<Uint8Array>, context: SandboxContext): Promise<Result<void>>tarAsyncIterable<Uint8Array>requiredThe archive, as the runtime's tree builder writes it: normal relative paths, symlinks inside the root.
contextSandboxContextrequiredThe authority to re-check with context.fence() at every provider request the import makes. See SandboxContext.
Returns an error value with one of these codes: stale_epoch, cleanup_claim_lost, unavailable.
SandboxInfo
What a sandbox adapter declares about itself: its provider name, whether it enforces egress, what its snapshots capture, browser and desktop support, which lost operations it can look up, and whether terminate can confirm a process is gone.
ExecOutput
What an adapter's exec returns: the complete output as byte streams, never truncated or buffered whole.