LangSmith Sandbox Module.
This module provides sandboxed code execution capabilities through the LangSmith Sandbox API.
Example:
from langsmith.sandbox import SandboxClient
client = SandboxClient()
with client.sandbox(template_name="python-sandbox") as sb: result = sb.run("python --version") print(result.stdout)
from langsmith.sandbox import AsyncSandboxClient
async with AsyncSandboxClient() as client: async with await client.sandbox(template_name="python-sandbox") as sb: result = await sb.run("python --version") print(result.stdout)
Async client for interacting with the Sandbox Server API.
This client provides an async interface for managing sandboxes and templates.
Represents an active sandbox for running commands and file operations async.
This class is typically obtained from AsyncSandboxClient.sandbox() and supports the async context manager protocol for automatic cleanup.
Client for interacting with the Sandbox Server API.
This client provides a simple interface for managing sandboxes and templates.
Raised when a command exceeds its timeout.
Raised when dataplane_url is not available for the sandbox.
This occurs when the sandbox-router URL is not configured for the cluster.
Raised when organization quota limits are exceeded.
Users should contact support@langchain.dev to increase quotas.
Raised when creating a resource that already exists.
Raised when resource provisioning fails.
Raised when deleting a resource that is still in use.
Raised when updating a resource name to one that already exists.
Raised when a resource is not found.
Raised when an operation times out.
Raised when the API endpoint returns an unexpected error.
For example, this is raised for wrong URL or path.
Raised when authentication fails (invalid or missing API key).
Base exception for sandbox client errors.
Raised when connection to the sandbox server fails.
Raised when attempting to interact with a sandbox that is not ready.
Raised when a sandbox operation fails (run, read, write).
Raised when the server sends a 1001 Going Away close frame.
This indicates a server hot-reload, not a true connection failure. The command is still running on the server.
This is a subclass of SandboxConnectionError, so the auto-reconnect logic in CommandHandle catches it along with all other connection errors. The distinction matters for retry strategy: SandboxServerReloadError triggers immediate reconnect (no backoff), while other SandboxConnectionError triggers exponential backoff.
Users typically never see this exception — it's handled internally.
Nothing is listening on the target port inside the sandbox.
Base exception for TCP tunnel errors.
The daemon rejected the port as not allowed.
Protocol version mismatch between the tunnel client and the daemon.
Raised when request validation fails.
This includes:
Async handle to a running command with streaming output and auto-reconnect.
Async iterable, yielding OutputChunk objects (stdout and stderr interleaved in arrival order). Access .result after iteration to get the full ExecutionResult.
Auto-reconnect behavior:
Construction modes (controlled by command_id):
command_id="", the default): call await handle._ensure_started() after construction to read the server's "started" message and populate command_id / pid.command_id set): skips the started-message read, since reconnect streams don't emit one.Handle to a running command with streaming output and auto-reconnect.
Iterable, yielding OutputChunk objects (stdout and stderr interleaved in arrival order). Access .result after iteration to get the full ExecutionResult.
Auto-reconnect behavior:
The auto-reconnect is transparent -- the iterator reconnects and continues yielding chunks without any user intervention. If all reconnect attempts are exhausted, SandboxConnectionError is raised.
Construction modes (controlled by command_id):
command_id="", the default): the constructor eagerly reads the server's "started" message to populate command_id and pid before returning.command_id set): skips the started-message read, since reconnect streams don't emit one.Result of executing a command in a sandbox.
A single chunk of streaming output from command execution.
Represents a Sandbox Pool for pre-provisioned sandboxes.
Pools pre-provision sandboxes from a template for faster startup. Instead of waiting for a new sandbox to be created, sandboxes can be served from a pre-warmed pool.
Note: Templates with volume mounts cannot be used in pools.
Resource specification for a sandbox.
Lightweight provisioning status for any async-created resource.
Represents a SandboxTemplate.
Templates define the image, resource limits, and volume mounts for sandboxes. All other container details are handled by the server with secure defaults.
Represents a persistent volume.
Volumes are persistent storage that can be mounted in sandboxes.
Specification for mounting a volume in a sandbox template.
Represents an active sandbox for running commands and file operations.
This class is typically obtained from SandboxClient.sandbox() and supports the context manager protocol for automatic cleanup.
Async wrapper around :class:Tunnel.
The underlying tunnel runs in background threads (TCP listener + bridges); async context-manager methods delegate to the sync tunnel via the event loop's executor.
Usage::
async with await sandbox.tunnel(remote_port=5432) as t: conn = await asyncpg.connect(host="127.0.0.1", port=t.local_port) TCP tunnel to a port inside a sandbox.
Opens a local TCP listener and forwards each accepted connection through a yamux-multiplexed WebSocket to the daemon, which dials the target port inside the sandbox.
Typically used as a context manager::
with sandbox.tunnel(remote_port=5432) as t: conn = psycopg2.connect(host="127.0.0.1", port=t.local_port) Or with explicit lifecycle::
t = sandbox.tunnel(remote_port=5432) # ... use tunnel ... t.close()