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.
Unique identifier (UUID). Remains constant even if name changes.
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.
Display name (can be updated).
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 a running command by its command ID.
Returns a new CommandHandle that resumes output from the given offsets.
Execute a command in the sandbox.
When wait is true (default) and no streaming callbacks are provided,
uses WebSocket, falling back to HTTP POST only when the optional ws
package isn't installed.
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();
}