Client for interacting with the Sandbox Server API.
This client provides a simple interface for managing sandboxes and snapshots.
Capture a snapshot from a running sandbox.
Blocks until the snapshot is ready (polls with 2s interval).
Create a new Sandbox.
Remember to call sandbox.delete() when done to clean up resources.
Build a snapshot from a Docker image.
Blocks until the snapshot is ready (polls with 2s interval).
Build a snapshot from a local Dockerfile context.
Creates a temporary builder sandbox, uploads the Docker build context, runs BuildKit inside the sandbox, and captures the built image as a LangSmith snapshot.
Delete a Sandbox.
Delete a snapshot.
Create a link that downloads one file from a sandbox.
The link carries its own token, so anyone holding the URL can fetch that one file without a LangSmith credential. It is pinned to the sandbox and the exact path and cannot be repointed at another file. 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.
Get a Sandbox by name.
The sandbox is NOT automatically deleted. Use deleteSandbox() for cleanup.
Get the provisioning status of a sandbox.
This is a lightweight endpoint designed for polling during async creation. Use this instead of getSandbox() when you only need the status.
Get a snapshot by ID.
List all Sandboxes.
List snapshots, optionally filtered and paginated server-side.
The backend always paginates this endpoint. When limit is omitted the
server applies a default page size (currently 50), so a single call is
not guaranteed to return every snapshot visible to the tenant. To iterate
through all results, repeat the call with increasing offset values (or
an explicit limit) until fewer than limit snapshots come back.
Generate an authenticated URL for an HTTP service running in a sandbox.
Without access, mints a short-lived token and returns a ServiceUrl
that refreshes it as it nears expiry. With access set to "restricted"
or "workspace" the URL is gated by LangSmith login instead and a
ServiceLoginUrl is returned: no token, no expiry, browser only.
A login grant is durable, so token mode is refused with 409 while one is
in place, and expiresInSeconds does not apply to the login modes.
Start a stopped sandbox and wait until ready.
Stop a running sandbox (preserves sandbox files for later restart).
Returns a string representation of the SandboxClient instance. This method is called when the object is converted to a string or logged, ensuring sensitive information like API keys is not exposed.
Update a sandbox's display name.
Wait for a sandbox to become ready.
Polls getSandboxStatus() until the sandbox reaches "ready" or "failed" status, then returns the full Sandbox object.
Poll until a snapshot reaches "ready" or "failed" status.
import { SandboxClient } from "langsmith/sandbox";
// Uses LANGSMITH_ENDPOINT and LANGSMITH_API_KEY from environment
const client = new SandboxClient();
// Or with explicit configuration
const client = new SandboxClient({
apiEndpoint: "https://api.smith.langchain.com/v2/sandboxes",
apiKey: "your-api-key",
});
// Create a sandbox with the default runtime
const sandbox = await client.createSandbox();
try {
const result = await sandbox.run("python --version");
console.log(result.stdout);
} finally {
await sandbox.delete();
}