LangSmith Sandbox Module.
This module provides sandboxed code execution capabilities through the LangSmith Sandbox API.
Example:
from langsmith.sandbox import SandboxClient
client = SandboxClient()
snapshot = client.create_snapshot( docker_image="python:3.12-slim", name="python-snapshot" ) with client.sandbox(snapshot_id=snapshot.id) as sb: result = sb.run("python --version") print(result.stdout)
from langsmith.sandbox import AsyncSandboxClient
async with AsyncSandboxClient() as client: snapshot = await client.create_snapshot( docker_image="python:3.12-slim", name="python-snapshot" ) async with await client.sandbox(snapshot_id=snapshot.id) as sb: result = await sb.run("python --version") print(result.stdout)
Build a GCS-backed sandbox mount specification.
Build a public Git-backed sandbox mount specification.
Build a high-level mount config from provider auth and mount specs.
The returned value is sent as the public mount_config field. The
backend expands provider auth into runtime proxy rules.
Build an S3-backed sandbox mount specification.
Build a sandbox proxy rule that signs AWS HTTPS requests.
The sandbox proxy keeps the real AWS credentials outside the sandbox and
signs supported AWS requests with SigV4 on the sandbox's behalf. AWS
credentials must be supplied as workspace_secret or opaque values;
plaintext AWS credentials are intentionally not supported.
Build a sandbox proxy rule that injects GCP OAuth bearer auth.
The sandbox proxy keeps the service account JSON outside the sandbox and
injects OAuth bearer tokens for built-in Google API host matching.
service_account_json must be supplied as a workspace_secret or
opaque value; plaintext service account JSON is intentionally not
supported.
Provide a write-only secret value for a proxy configuration.
The value is sent when creating or updating the sandbox proxy config, but LangSmith stores it as an opaque secret and does not return it from the API.
Build a sandbox proxy config from one or more proxy rules.
Use provider-specific rule helpers such as aws_auth and gcp_auth
when a sandbox needs multiple auth flows.
Create a LangSmith workspace secret reference for a proxy configuration.
Async client for interacting with the Sandbox Server API.
This client provides an async interface for managing sandboxes and snapshots.
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 snapshots.
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 technical support via our Support Portal (https://support.langchain.com) 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.Async variant of :class:ServiceURL with auto-refreshing token.
Properties and HTTP helpers are async. Use with
:meth:AsyncSandboxClient.service or :meth:AsyncSandbox.service.
Example::
svc = await sb.service(port=3000)
resp = await svc.get("/api/data")
print(await svc.get_browser_url())
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.
Lightweight provisioning status for any async-created resource.
Authenticated URL for accessing an HTTP service running in a sandbox.
Properties auto-refresh the token transparently when it nears expiry.
HTTP helper methods (.get, .post, etc.) inject the auth header
automatically.
When constructed by :meth:SandboxClient.service or
:meth:Sandbox.service, the object holds an internal refresher that
re-calls the API to obtain a fresh token before the current one expires.
Example::
svc = sb.service(port=3000)
resp = svc.get("/api/data") # token injected + auto-refreshed
print(svc.browser_url) # always-fresh URL
Represents a sandbox snapshot.
Snapshots are built from Docker images or captured from running sandboxes. They are used to create new sandboxes.
AWS credentials used by the backend to authenticate S3 mounts.
GCP credentials used by the backend to authenticate GCS mounts.
GCS configuration for a sandbox mount.
GCS-backed sandbox mount specification.
Git configuration for a sandbox mount.
Git ref selected for a sandbox mount.
Git-backed sandbox mount specification.
Optional per-mount cache configuration supported by bucket mounts.
S3 configuration for a sandbox mount.
S3-backed sandbox mount specification.
Provider auth blocks for sandbox mounts.
Public mount config sent to the sandbox API.
A secret value that can be used by sandbox proxy rules.
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()