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.
LangSmith access granted to code inside the sandbox, or undefined when it has none.
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).
User, working directory and environment this sandbox's commands run with. Absent on sandboxes created before the server recorded it.
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.
Create a link that downloads one file from this sandbox.
The link carries its own token, so anyone holding the URL can fetch that one file without a LangSmith credential. Fetching wakes a stopped sandbox.
Do not modify the file after minting a link for it. The link is pinned to a path, not to a snapshot of the contents, so a later write to that path may or may not be reflected in what the link serves. Write a new file and mint a new link when the contents change.
Find files and directories matching a pattern.
Search file contents for a literal string.
List a directory's immediate entries, without recursing.
A convenience over glob with the pattern *.
Read a file from the sandbox.
Read part of a file, for chunked reads and resumed downloads.
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.
Report a file's size and validators without transferring it.
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();
}