Skip to main content

​
Prerequisites

  • MODAL_TOKEN_ID and MODAL_TOKEN_SECRET from modal.com/settings
  • ANTHROPIC_API_KEY or OPENAI_API_KEY

​
TypeScript example

npm install sandbox-agent@0.4.x modal

import { SandboxAgent } from "sandbox-agent";
import { modal } from "sandbox-agent/modal";

const secrets: Record<string, string> = {};
if (process.env.ANTHROPIC_API_KEY) secrets.ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
if (process.env.OPENAI_API_KEY) secrets.OPENAI_API_KEY = process.env.OPENAI_API_KEY;
const baseImage = process.env.MODAL_BASE_IMAGE ?? "node:22-slim";

const sdk = await SandboxAgent.start({
  sandbox: modal({
    image: baseImage,
    create: { secrets },
  }),
});

try {
  const session = await sdk.createSession({ agent: "claude" });
  const response = await session.prompt([
    { type: "text", text: "Summarize this repository" },
  ]);
  console.log(response.stopReason);
} finally {
  await sdk.destroySandbox();
}
The modal provider handles app creation, image building, sandbox provisioning, agent installation, server startup, and tunnel networking automatically. Set image to change the base Docker image before Sandbox Agent and its agent binaries are layered on top. You can also pass a prebuilt Modal Image object.

​
Faster cold starts

Modal caches image layers, so the Dockerfile commands that install curl and sandbox-agent only run on the first build. Subsequent sandbox creates reuse the cached image.

​
Notes

  • Modal sandboxes use gVisor for strong isolation.
  • Ports are exposed via encrypted tunnels (encryptedPorts). The provider uses sb.tunnels() to get the public HTTPS URL.
  • Environment variables (API keys) are passed as Modal Secrets for security.