LangSmith Sandbox Module.
This module provides sandboxed code execution capabilities through the LangSmith Sandbox API.
import { ... } from "langsmith/sandbox";Sign supported AWS HTTPS requests using static keys or an IAM role. Role auth requires backend support and is configured at sandbox creation. LangSmith supplies the workspace External ID and renews credentials. A role in proxyConfig uses its effective IAM permissions; the same helper in mountConfig.auth uses the backend's mount-scoped S3 permissions.
Build a read-only Context Hub mount. The sync is one-way: files written under the mount path inside the sandbox are never pushed back to the repo, and the next sync overwrites them.
Build a sandbox proxy rule that injects GCP OAuth bearer auth.
Build mount-scoped auth, or use an enabled AWS rule from proxyConfig for S3. Pass the same proxyConfig to sandbox creation; its general IAM permissions remain unchanged. GCS mounts still require explicit GCP auth in this config.
Provide a write-only secret value for a sandbox proxy configuration.
Build a sandbox proxy config from one or more proxy rules.
Rejects grants the server would refuse, without the round trip.
Reference a LangSmith workspace secret in a sandbox proxy configuration.
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:
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 (general-purpose).
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).
Raised when connection to the sandbox server fails.
Thrown when the socket fails or times out before the WebSocket handshake.
The execute frame was never sent, so re-issuing the same command ID cannot double-run a command.
Raised when sandbox creation fails.
Base exception for sandbox client errors.
Raised when attempting to interact with a sandbox that is not ready.
Raised when a sandbox operation fails (run, read, write).
Raised when a transient connection failure occurs before a command starts.
run() retries this error with the same command ID so the server can
deduplicate an attempt whose outcome is unknown.
Raised when the sandbox server is reloading (close code 1001).
Subclass of connection error that signals immediate reconnect (no backoff).
Raised when a sandbox user token or proxy callback signature fails verification.
Raised when request validation fails.
This includes:
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.
Client for interacting with the Sandbox Server API.
This client provides a simple interface for managing sandboxes and snapshots.
Verifies tokens LangSmith signs for code running in or behind a sandbox.
Keys are fetched from LangSmith's JWKS endpoint and cached. Requires Web Crypto Ed25519 support (Node.js 20+, Deno, Bun, Cloudflare Workers).
Service URL gated by LangSmith login rather than a token.
The grant is durable: no token, no expiry, and only usable from a browser signed in to LangSmith — which is why there is no fetch helper here, a programmatic request cannot satisfy the login.
Service URL carrying a short-lived token, refreshed as it nears expiry.
Accessors are async because a refresh is a network call.
import { SandboxClient } from "langsmith/sandbox";
// Uses LANGSMITH_ENDPOINT and LANGSMITH_API_KEY from environment
const client = new SandboxClient();
const snapshot = await client.createSnapshot(
"python",
"python:3.12-slim",
1_073_741_824
);
const sandbox = await client.createSandbox(snapshot.id);
try {
const result = await sandbox.run("python --version");
console.log(result.stdout);
} finally {
await sandbox.delete();
}Grant letting code inside a sandbox call the LangSmith API as the creator.
INHERIT tracks everything the creator can do; EXPLICIT is capped to
permissions. Permissions are a ceiling re-checked on every request rather
than a snapshot, so access the creator loses is lost here too.
Options for capturing a snapshot from a running sandbox.
Context Hub configuration for a sandbox mount.
Read-only Context Hub-backed sandbox mount specification.
Options for creating a snapshot from a local Dockerfile context.
Options for creating a sandbox.
Options for creating a snapshot from a Docker image.
A link that downloads one sandbox file with no LangSmith credential.
The link is pinned to the sandbox, the file path, and the response headers, so it cannot be repointed at another file. It is pinned to the path rather than to a snapshot of the contents, so the file must not be modified while the link is in use.
Result of executing a command in a sandbox.
Bytes returned by a ranged read, and where they sit in the file.
One filesystem entry returned by sandbox.glob().
What a HEAD on a sandbox file reports, without transferring it.
GCS configuration for a sandbox mount.
GCS-backed sandbox mount specification.
Options for minting a sandbox file download link.
Git configuration for a sandbox mount.
Git ref selected for a sandbox mount.
Git-backed sandbox mount specification.
Options for the read-only filesystem search operations.
Entries matching a glob pattern.
One matching line found by sandbox.grep().
Options for sandbox.grep().
Lines matching a literal search.
Options for listing snapshots. All fields are optional and independent.
The backend always paginates: when limit is omitted the server applies
a default page size (currently 50), so a single call will not necessarily
return every snapshot visible to the caller's tenant.
Optional per-mount cache configuration supported by bucket mounts.
A single chunk of streaming output from command execution.
Options for a ranged read. Provide start (with optional end), or
suffixBytes.
Lightweight provisioning status for any async-created resource.
The user, working directory and environment commands run with.
Mirrors docker run -u / -w / -e: user and work_dir replace the layer
below, env_vars merge into it key by key. It applies at three points, each
layered over the one before -- the snapshot, the sandbox, and a single
command.
Options for running a command in a sandbox.
S3 configuration for a sandbox mount. Field names are snake_case so the
object is wire-compatible with the backend MountSpec type.
S3-backed sandbox mount specification.
Network access-control rules for a sandbox's proxy sidecar.
Supported pattern types: exact domains, globs (e.g. *.example.com),
IPs, CIDR ranges (e.g. 10.0.0.0/8), and regex (~pattern).
Only one of allow_list and deny_list may be populated.
AWS auth rule for sandbox proxy SigV4 signing.
AWS credentials used by the backend to authenticate S3 mounts.
A verified proxy callback payload.
The sandbox whose outbound request triggered a proxy callback.
Snapshot of the outbound request, sent for full_request callbacks.
Configuration options for the SandboxClient.
Data representing a sandbox instance from the API.
GCP auth rule for sandbox proxy OAuth bearer injection.
GCP credentials used by the backend to authenticate GCS mounts.
Provider auth blocks for sandbox mounts.
Public mount config sent to the sandbox API.
Full proxy configuration forwarded to the sandbox server as-is (snake_case
so it's wire-compatible with the backend). Mirrors the server's
ProxyConfig type.
Secret value reference for sandbox proxy rules.
The LangSmith user a service URL request was made by.
Represents a sandbox snapshot.
Snapshots are built from Docker images or captured from running sandboxes. They are used to create new sandboxes.
Options for starting a stopped sandbox.
Options for updating a sandbox (name, retention settings, proxy config).
Options for waiting for a sandbox to become ready.
Options for waiting for a snapshot to become ready.
Internal WebSocket message type from the server.
Options for the low-level WebSocket stream functions.
How a delegation grant derives its permission set.
An exact audience, or a predicate called with each audience in the token.
How a download link asks the browser to handle the file.
Sandbox mount specification.
Provider auth helper output accepted by mountConfig.
Proxy rule accepted by the sandbox proxy config.
How a service URL is gated. Omit for a minted token.
Header carrying the signature of a proxy callback request.
Header the sandbox router reads the minted service token from.
Header carrying the signed identity of a LangSmith-login service URL request.