@langchain/modal

Modal Sandbox backend for deepagents. This package provides a ModalSandbox implementation of the SandboxBackendProtocol, enabling agents to execute commands, read/write files, and manage isolated container environments using Modal's serverless infrastructure.

Features

• Isolated Execution: Run commands in secure, isolated containers on Modal's serverless infrastructure
• GPU Support: Access NVIDIA GPUs (T4, L4, A10G, A100, H100) for ML/AI workloads
• Custom Images: Use any Docker image from public registries
• File Operations: Upload and download files with full filesystem access
• Volume Mounts: Mount Modal Volumes for persistent storage
• Secrets Injection: Securely inject Modal Secrets as environment variables
• BaseSandbox Integration: All inherited methods (read, write, edit, ls, grep, glob) work out of the box
• Factory Pattern: Compatible with deepagents' middleware architecture
• Full SDK Access: Access the underlying Modal SDK via the sandbox property for advanced features

Installation

# npm
npm install @langchain/modal

# yarn
yarn add @langchain/modal

# pnpm
pnpm add @langchain/modal

Authentication Setup

The package requires Modal authentication:

Environment Variables (Recommended)

1. Go to https://modal.com/settings/tokens
2. Create a new token and set the environment variables:

export MODAL_TOKEN_ID=your_token_id
export MODAL_TOKEN_SECRET=your_token_secret

Explicit Credentials in Code

const sandbox = await ModalSandbox.create({
  auth: {
    tokenId: "your-token-id",
    tokenSecret: "your-token-secret",
  },
});

Basic Usage

import { createDeepAgent } from "deepagents";
import { ChatAnthropic } from "@langchain/anthropic";
import { ModalSandbox } from "@langchain/modal";

// Create and initialize the sandbox
const sandbox = await ModalSandbox.create({
  imageName: "python:3.12-slim",
  timeoutMs: 600_000, // 10 minutes
});

try {
  const agent = createDeepAgent({
    model: new ChatAnthropic({ model: "claude-sonnet-4-20250514" }),
    systemPrompt: "You are a coding assistant with access to a sandbox.",
    backend: sandbox,
  });

  const result = await agent.invoke({
    messages: [
      { role: "user", content: "Create a hello world Python app and run it" },
    ],
  });
} finally {
  await sandbox.close();
}

Configuration Options

ModalSandboxOptions extends the Modal SDK's SandboxCreateParams directly, so you can use any SDK option. We only wrap volumes and secrets to accept names instead of objects.

interface ModalSandboxOptions extends SandboxCreateParams {
  /** Modal App name. @default "deepagents-sandbox" */
  appName?: string;

  /** Docker image to use. @default "alpine:3.21" */
  imageName?: string;

  /** Initial files to populate the sandbox with. */
  initialFiles?: Record<string, string | Uint8Array>;

  /** Authentication credentials (or use env vars). */
  auth?: { tokenId?: string; tokenSecret?: string };

  /** Modal Volume names to mount (keys are mount paths). */
  volumes?: Record<string, string>;

  /** Modal Secret names to inject. */
  secrets?: string[];

  // All SandboxCreateParams options are available:
  timeoutMs?: number; // Max lifetime in milliseconds
  idleTimeoutMs?: number; // Idle timeout in milliseconds
  workdir?: string; // Working directory
  gpu?: string; // GPU type (e.g., "T4", "A100")
  cpu?: number; // CPU cores (fractional allowed)
  memoryMiB?: number; // Memory in MiB
  regions?: string[]; // Regions to run in
  env?: Record<string, string>; // Environment variables
  blockNetwork?: boolean; // Block network access
  cidrAllowlist?: string[]; // Allowed CIDRs
  verbose?: boolean; // Enable verbose logging
  name?: string; // Sandbox name (unique within app)
}

GPU Support

Modal supports various NVIDIA GPUs for ML/AI workloads:

const sandbox = await ModalSandbox.create({
  imageName: "python:3.12-slim",
  gpu: "T4", // NVIDIA T4 (16GB VRAM)
  // gpu: "L4",    // NVIDIA L4 (24GB VRAM)
  // gpu: "A10G",  // NVIDIA A10G (24GB VRAM)
  // gpu: "A100",  // NVIDIA A100 (40/80GB VRAM)
  // gpu: "H100",  // NVIDIA H100 (80GB VRAM)
});

Using Volumes

Mount Modal Volumes for persistent storage:

// Volume must be created in Modal first
const sandbox = await ModalSandbox.create({
  imageName: "python:3.12-slim",
  volumes: {
    "/data": "my-data-volume",
    "/models": "my-models-volume",
  },
});

// Files in /data and /models persist across sandbox restarts
await sandbox.execute("echo 'Hello' > /data/test.txt");

Using Secrets

Inject Modal Secrets as environment variables:

// Secrets must be created in Modal first
const sandbox = await ModalSandbox.create({
  imageName: "python:3.12-slim",
  secrets: ["my-api-keys", "database-credentials"],
});

// Secrets are available as environment variables
await sandbox.execute("echo $API_KEY");

Initial Files

Pre-populate the sandbox with files during creation:

const sandbox = await ModalSandbox.create({
  imageName: "python:3.12-slim",
  initialFiles: {
    // String content
    "/app/main.py": `
import json

def main():
    print("Hello from Python!")

if __name__ == "__main__":
    main()
`,
    // JSON configuration
    "/app/config.json": JSON.stringify(
      { name: "my-app", version: "1.0.0" },
      null,
      2,
    ),

    // Uint8Array content also supported
    "/app/data.bin": new Uint8Array([0x00, 0x01, 0x02]),
  },
});

// Files are ready to use immediately
const result = await sandbox.execute("python /app/main.py");
console.log(result.output); // "Hello from Python!"

This is especially useful for:

• Setting up project scaffolding before agent execution
• Providing configuration files
• Pre-loading test data or fixtures
• Creating initial source code files

Accessing the Modal SDK

For advanced features not exposed by BaseSandbox, you can access the underlying Modal SDK directly:

• .client - The ModalClient instance for accessing other Modal resources
• .instance - The Sandbox instance for direct sandbox operations

const modalSandbox = await ModalSandbox.create();

// Access the Modal client for other Modal resources
const client = modalSandbox.client;

// Access the raw Modal Sandbox for direct operations
const instance = modalSandbox.instance;

// Execute commands with specific options
const process = await instance.exec(["python", "-c", "print('Hello')"], {
  stdout: "pipe",
  stderr: "pipe",
});

// Open files for reading/writing
const writeHandle = await instance.open("/tmp/file.txt", "w");
await writeHandle.write(new TextEncoder().encode("Hello"));
await writeHandle.close();

Reconnecting to Existing Sandboxes

Resume working with a sandbox that is still running:

// First session: create a sandbox
const sandbox = await ModalSandbox.create({
  imageName: "python:3.12-slim",
  timeout: 3600, // 1 hour
});
const sandboxId = sandbox.id;

// Later: reconnect to the same sandbox by ID
const reconnected = await ModalSandbox.fromId(sandboxId);
const result = await reconnected.execute("ls -la");

// Or reconnect by name (if sandbox has a name)
const sandbox2 = await ModalSandbox.create({
  appName: "my-app",
  sandboxName: "my-sandbox",
  imageName: "python:3.12-slim",
});

const reconnected2 = await ModalSandbox.fromName("my-app", "my-sandbox");

Error Handling

import { ModalSandboxError } from "@langchain/modal";

try {
  await sandbox.execute("some command");
} catch (error) {
  if (error instanceof ModalSandboxError) {
    switch (error.code) {
      case "NOT_INITIALIZED":
        await sandbox.initialize();
        break;
      case "COMMAND_TIMEOUT":
        console.error("Command took too long");
        break;
      case "AUTHENTICATION_FAILED":
        console.error("Check your Modal token credentials");
        break;
      default:
        throw error;
    }
  }
}

Error Codes

Code	Description
NOT_INITIALIZED	Sandbox not initialized - call initialize()
ALREADY_INITIALIZED	Cannot initialize twice
AUTHENTICATION_FAILED	Invalid or missing Modal tokens
SANDBOX_CREATION_FAILED	Failed to create sandbox
SANDBOX_NOT_FOUND	Sandbox ID/name not found or expired
COMMAND_TIMEOUT	Command execution timed out
COMMAND_FAILED	Command execution failed
FILE_OPERATION_FAILED	File read/write failed
RESOURCE_LIMIT_EXCEEDED	CPU, memory, or storage limits exceeded
VOLUME_ERROR	Volume operation failed

Inherited BaseSandbox Methods

ModalSandbox extends BaseSandbox and inherits these convenience methods:

Method	Description
read()	Read a file's contents
write()	Write content to a file
edit()	Replace text in a file
lsInfo()	List directory contents
grepRaw()	Search for patterns in files
globInfo()	Find files matching a pattern

Limits and Constraints

Constraint	Value
Max timeout	86400 seconds (24 hours)
Default timeout	300 seconds (5 minutes)
Network access	Full (by default, can be blocked)
File API	Alpha (up to 100 MiB read, 1 GiB write)

Environment Variables

Variable	Description
MODAL_TOKEN_ID	Modal API token ID
MODAL_TOKEN_SECRET	Modal API token secret

License

MIT