Sandbox KitModal
Install the Modal provider, set a token pair and an app name, and create a sandbox from an image.
A Modal sandbox starts from a container image. You need a Modal token pair and an app that already exists. This client talks to Modal SDK v0.11.1.
Install
npm install @sandbox-kit/sandbox @sandbox-kit/modalCreate a sandbox
Set MODAL_TOKEN_ID, MODAL_TOKEN_SECRET, and MODAL_APP_NAME. This program uses the environment main when MODAL_ENVIRONMENT is unset.
import { modal } from "@sandbox-kit/modal";
import { Client } from "@sandbox-kit/sandbox";
await using client = new Client({
provider: modal(),
auth: {
tokenPair: {
id: process.env.MODAL_TOKEN_ID!,
secret: process.env.MODAL_TOKEN_SECRET!,
},
},
scope: {
appName: process.env.MODAL_APP_NAME!,
environment: process.env.MODAL_ENVIRONMENT ?? "main",
},
timeout: 120_000,
});
const sandbox = await client.create({
source: { image: { reference: "alpine:3.21" } },
resources: { cpuCores: 0.5, memoryMib: 512n },
lifetime: { maximumLifetime: 5 * 60_000 },
});
console.log(sandbox.id);timeout and maximumLifetime are milliseconds. memoryMib is a bigint. await using closes the client when the block ends. Call await client.close() in a finally block when that syntax is unavailable.
Omit auth when the Modal SDK should use credentials it already finds in the environment or a Modal profile. scope.appName stays required. endpoint is rejected. Closing the client does not terminate the sandbox.
Where to go next
| You want to | Open |
|---|---|
| A command, a region, ports, or an idle timeout | Create a sandbox |
| Attach to a sandbox and terminate it | Manage a sandbox |
| Work with files | Use files |
| A failed call | Read an error |
| A project you can run | create-modal-sandbox and the Go project |