Represents an active sandbox for running commands and file operations.
This class is typically obtained from SandboxClient.createSandbox() and provides methods for command execution and file I/O within the sandbox environment.
Timestamp when the sandbox was created.
URL for data plane operations (file I/O, command execution).
Seconds after the sandbox enters the stopped state before it (and
its filesystem clone) are permanently deleted (0 means disabled).
Root filesystem capacity in bytes.
Optionally, a unique identifier for the run.
Idle timeout TTL in seconds (0 means disabled).
New sandboxes receive a server-side default of 600 seconds (10 minutes)
when the caller did not set idleTtlSeconds explicitly. The launcher
stops the sandbox after this many idle seconds.
Memory allocation in bytes.
A human-readable name for the run.
Snapshot ID used to create this sandbox.
Provisioning status ("provisioning", "ready", "failed", "stopped").
Human-readable status message (e.g., error details when failed).
Timestamp when the sandbox transitioned to stopped, or undefined
while running. The deletion deadline is
stopped_at + delete_after_stop_seconds.
Timestamp when the sandbox was last updated.
Number of vCPUs allocated.
Capture a snapshot from this sandbox.
Delete this sandbox.
Read a file from the sandbox.
Reconnect to this command from the last known offsets.
Returns a new CommandHandle that resumes output from where this one left off.
Execute a command in the sandbox.
When wait is true (default) and no streaming callbacks are provided,
tries WebSocket first and falls back to HTTP POST.
When wait is false or streaming callbacks are provided, uses WebSocket
(required). Returns a CommandHandle for streaming output.
Start a stopped sandbox and wait until ready.
Updates this sandbox's status and dataplane_url in place.
Stop a running sandbox (preserves sandbox files for later restart).
Write content to a file in the sandbox.
const sandbox = await client.createSandbox(snapshot.id);
try {
const result = await sandbox.run("python --version");
console.log(result.stdout);
} finally {
await sandbox.delete();
}