SandboxSession
One live sandbox, as an adapter returns it from create, restore or attach: run commands, move files, snapshot and close it.
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.
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.
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.
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.