class ModalSandboxModal Sandbox backend for deepagents.
Extends BaseSandbox to provide command execution, file operations, and
sandbox lifecycle management using Modal's serverless infrastructure.
import { ModalSandbox } from "@langchain/modal";
// Create and initialize a sandbox
const sandbox = await ModalSandbox.create({
imageName: "python:3.12-slim",
timeout: 600,
});
try {
// Execute commands
const result = await sandbox.execute("python --version");
console.log(result.output);
} finally {
// Always cleanup
await sandbox.close();
}import { createDeepAgent } from "deepagents";
import { ModalSandbox } from "@langchain/modal";
const sandbox = await ModalSandbox.create();
const agent = createDeepAgent({
model: new ChatAnthropic({ model: "claude-sonnet-4-20250514" }),
systemPrompt: "You are a coding assistant with sandbox access.",
backend: sandbox,
});Close the sandbox and release all resources.
After closing, the sandbox cannot be used again. This terminates the sandbox container on Modal.
Download files from the sandbox.
Each file is read individually using Modal's file API, allowing partial success when some files exist and others don't.
Edit a file by replacing string occurrences.
Uses downloadFiles() to read, performs string replacement in TypeScript, then uploadFiles() to write back. No runtime needed on the sandbox host.
Memory-conscious: releases intermediate references early so the GC can reclaim buffers before the next large allocation is made.
Execute a command in the sandbox.
Commands are run using sh -c to execute the command string. Uses sh instead of bash for compatibility with minimal images like Alpine.
Structured glob matching returning FileInfo objects.
Uses pure POSIX shell (find + stat) via execute() to list all files, then applies glob-to-regex matching in TypeScript. No Python or Node.js needed on the sandbox host.
Glob patterns are matched against paths relative to the search base:
* matches any characters except /** matches any characters including / (recursive)? matches a single character except /[...] character classesSearch for a literal text pattern in files using grep.
Initialize the sandbox by creating a new Modal Sandbox instance.
This method authenticates with Modal and provisions a new sandbox container.
After initialization, the id property will reflect the actual Modal sandbox ID.
List files and directories in the specified directory (non-recursive).
Uses pure POSIX shell (find + stat) via execute() — works on any Linux including Alpine. No Python or Node.js needed.
Poll the sandbox status to check if it has finished running.
Read file content with line numbers.
Uses pure POSIX shell (awk) via execute() — only the requested slice is returned over the wire, making this efficient for large files. Works on any Linux including Alpine (no Python or Node.js needed).
Read file content as raw FileData.
Uses downloadFiles() directly — no runtime needed on the sandbox host.
Alias for close() to maintain compatibility with other sandbox implementations.
Terminate the sandbox.
Alias for close() for Modal SDK compatibility.
Upload files to the sandbox.
Files are written to the sandbox filesystem using Modal's file API. Parent directories are created automatically if they don't exist.
Wait for the sandbox to finish running.
Create a new file with content.
Uses downloadFiles() to check existence and uploadFiles() to write. No runtime needed on the sandbox host.
Create and initialize a new ModalSandbox in one step.
This is the recommended way to create a sandbox. It combines construction and initialization into a single async operation.
Reconnect to an existing sandbox by ID.
This allows you to resume working with a sandbox that was created earlier and is still running.
Get a running sandbox by name from a deployed app.