Skip to content
Sandbox SDK
Esc
↑↓navigate↵open⌘Jpreview
On this page

Modal

Use Modal Sandboxes from TypeScript through the official modal SDK and one portable API. Exact keys, CPU and memory sizing, regions, snapshots, image templates, network policies and previews.

modal() runs each sandbox as a Modal Sandbox through Modal’s official JavaScript SDK, the modal npm package.

With @opencoredev/sandbox-sdk you call createSandbox(modal()) and then box.run, box.files and box.preview, and the same code runs on E2B or Vercel when you swap the factory. Modal has no pause and no terminal through this API; the capability matrix lists what differs per provider, and box.native is the modal Sandbox object when you need the rest.

Install

npm install @opencoredev/sandbox-sdk modal
pnpm add @opencoredev/sandbox-sdk modal
yarn add @opencoredev/sandbox-sdk modal
bun add @opencoredev/sandbox-sdk modal

The adapter needs modal 0.11.1 or later. Create a token in the Modal dashboard and set MODAL_TOKEN_ID and MODAL_TOKEN_SECRET, or run modal setup to write ~/.modal.toml. Modal’s API is gRPC, so this adapter loads the SDK instead of calling an HTTP API itself.

Quickstart

import { createSandbox } from "@opencoredev/sandbox-sdk";
import { modal } from "@opencoredev/sandbox-sdk/modal";

await using box = await createSandbox(modal(), { timeoutMs: 30 * 60_000 });
const result = await box.run("node --version");
console.log(result.stdout);

await using terminates the sandbox when the block ends. Pass timeoutMs: without it, Modal stops a sandbox after 5 minutes.

What it supports

Feature Support Notes
Commands and streaming Yes Live output
Files Yes Modal’s filesystem API
Background processes Yes
Preview URLs Yes Public https:// tunnels; declare ports at creation
Pause and resume No Modal sandboxes can’t stop and run again
Snapshots Partial File system only, as an image; with expiresInMs
Snapshot deletion Yes deleteSnapshot()
Templates Yes buildTemplate() builds a Modal image
Machine size Partial Presets or exact CPU and memory; no disk setting
Network policy Yes "none", or an allow list of domains, wildcards, IPs and CIDRs
Hard lifetime (timeoutMs) Yes Whole seconds, up to 24 hours
Idle timeout (idleTimeoutMs) Yes Whole seconds
Keys Exact Sandbox name is a hash of the key
Terminal No

Run commands

Await box.run for the result, or iterate it to stream output as it arrives.

import { createSandbox } from "@opencoredev/sandbox-sdk";
import { modal } from "@opencoredev/sandbox-sdk/modal";

await using box = await createSandbox(modal());
const result = await box.run("ls -la", { cwd: "/workspace", timeoutMs: 30_000 });
console.log(result.exitCode, result.stdout);

for await (const chunk of box.run("for i in 1 2 3; do echo $i; sleep 1; done")) {
  process.stdout.write(chunk.text);
}

Background processes and previews

Modal tunnels only ports declared at creation. Previewing another port fails with invalid_argument. Preview URLs are public https:// addresses on modal.host.

import { createSandbox } from "@opencoredev/sandbox-sdk";
import { modal } from "@opencoredev/sandbox-sdk/modal";

await using box = await createSandbox(modal(), { ports: [5173], timeoutMs: 30 * 60_000 });
await box.start("npx vite --port 5173 --host", { name: "vite", ready: { port: 5173 } });
const preview = await box.preview(5173);
console.log(preview.url);

Snapshots and templates

snapshot() saves the sandbox’s file system as a Modal image and returns its ID. Running processes are not kept: a sandbox created from the snapshot marks restored process records failed with exit code 137. Restart them by name. Modal keeps a snapshot for 30 days by default; expiresInMs: 0 keeps it until you delete it.

import { buildTemplate, createSandbox, deleteSnapshot } from "@opencoredev/sandbox-sdk";
import { modal } from "@opencoredev/sandbox-sdk/modal";

const provider = modal();
await using box = await createSandbox(provider);
await box.run("npm init -y && npm install zod");
const { id } = await box.snapshot({ expiresInMs: 7 * 24 * 60 * 60_000 });
await using copy = await createSandbox(provider, { from: id });
await deleteSnapshot(provider, id);

const template = await buildTemplate(provider, {
  name: "python-tools",
  image: "python:3.13-slim",
  run: ["pip install --no-cache-dir requests"],
});
await using fromTemplate = await createSandbox(provider, { from: template.id });

buildTemplate() turns run steps into Dockerfile RUN layers on image (default: the factory’s image) and waits for Modal to build them. env applies to the build steps only. Modal caches built layers, so building the same steps again takes seconds. A template has no size; pass size to createSandbox instead, or buildTemplate() fails with unsupported. timeoutMs and signal stop the wait, though Modal may finish the image anyway, and Modal’s JavaScript SDK reports no build logs, so onLog is never called. Snapshots and templates are both images, so deleteSnapshot() deletes either.

Size, network, region, and lifetime

Preset Modal cpu Memory
small 1 2048 MiB
medium 2 4096 MiB
large 4 8192 MiB
import { createSandbox } from "@opencoredev/sandbox-sdk";
import { modal } from "@opencoredev/sandbox-sdk/modal";

await using box = await createSandbox(modal({ region: "us-east" }), {
  size: { cpu: 4, memoryMb: 8192 },
  network: { allow: ["registry.npmjs.org", "*.github.com"] },
  timeoutMs: 60 * 60_000,
  idleTimeoutMs: 10 * 60_000,
});

A size sets both Modal’s request and its limit, so the sandbox gets exactly that CPU and memory and cannot burst. cpu is Modal’s CPU count, from 0.125 up, and may be fractional. Modal has no disk setting, so diskGb fails with unsupported.

What a Modal cpu is depends on whose words you use. Modal’s docs call one cpu a physical core, billed as “2 vCPU equivalent”. Inside the sandbox, cpu: N shows N processors and runs N threads at full speed, not 2N. On November 9, 2026 we ran a fixed CPU job (SHA-256 over an in-memory buffer, 1, 2, 4 and 8 copies at once, three repeats each) on Modal and on an E2B 4 vCPU / 8 GiB sandbox:

Sandbox nproc One copy (s) Effective threads at 4 / 8 copies Throughput at 8 copies vs E2B
Modal cpu: 2, 8 GiB 2 1.27 2.2 / 2.0 0.53×
Modal cpu: 4, 8 GiB 4 1.27 4.0 / 4.1 1.10×
E2B 4 vCPU, 8 GiB template 4 1.02 3.0 / 3.0 1.00×

Effective threads is copies × one-copy time ÷ wall time. So 4 vCPU and 8 GiB on Modal is { cpu: 4, memoryMb: 8192 }: it matches E2B’s four CPUs and 8 GiB as the guest sees them, and its parallel throughput is about 10% higher. cpu: 2 delivers half. You pay for four Modal cores, which Modal itself would call 8 vCPU equivalent. That is one sandbox per setting on one day, so treat the percentages as rough.

Without size, Modal’s default applies: a request of 0.125 CPU and 128 MiB that bursts into spare host capacity, about 16 more CPUs and the host’s free memory. Billing follows the higher of the request and what the sandbox uses. Set resources on the factory for Modal’s own request and limit fields, such as a request with a higher burst limit.

network: "none" sends empty outbound allow lists, which block every outbound connection, hostnames and raw IPs alike. An allow list sends domains (with *. wildcards) and IPv4 or IPv6 addresses and CIDRs to the same lists. Previews are inbound, so neither blocks them. The adapter doesn’t use Modal’s blockNetwork, which also cuts the tunnels previews go through.

region pins sandboxes to Modal regions, such as "us-east" (Virginia) or the broader "us". It defaults to MODAL_SANDBOX_REGION, a comma-separated list. Without it Modal places each sandbox where it has capacity, anywhere in its fleet. Pinning costs more; see Pricing.

timeoutMs is the hard lifetime, rounded up to whole seconds and capped at 24 hours. Without it, Modal stops a sandbox after 5 minutes; set the factory’s timeoutMs to change that default for every sandbox. idleTimeoutMs stops a sandbox with no running command, no stdin and no open tunnel connection for that long.

Pricing and billing

Modal bills sandboxes per second for CPU and memory, at three times its Function list price because sandboxes run on non-preemptible capacity. Rates checked November 9, 2026:

Resource Per second Per hour
CPU $0.00003942 per Modal cpu $0.1419
Memory $0.00000667 per GiB $0.0240
  • Modal charges the higher of the request and actual use, with a minimum request of 0.125 CPU. A sized sandbox pays for its full size for its whole life.
  • { cpu: 4, memoryMb: 8192 } costs about $0.76 an hour.
  • Pinning a region multiplies the price: 1.15× for a broad region such as us, 1.75× for a narrow one such as us-east.
  • Plans include monthly credits ($30 on Starter, $100 on Team).

Sources: pricing, sandbox resources, region selection.

To see what you were charged, use Modal’s billing reports: Workspace.billing.report() in the Python SDK or modal billing report on the CLI. They report cost per App and tag by hour or day, before credits, and are available on the Team and Enterprise plans. Modal’s JavaScript SDK has no billing method, and box.usage() reports only the SDK’s own counters.

Configuration

Option Type Default Env var
tokenId string Profile MODAL_TOKEN_ID
tokenSecret string Profile MODAL_TOKEN_SECRET
environment string Profile’s MODAL_ENVIRONMENT
app string "sandbox-sdk"
image string, a registry tag such as "python:3.13-slim" "node:22-bookworm"
region string or string[], such as "us-east" Modal’s choice MODAL_SANDBOX_REGION
runtime "gvisor" or "vm" Modal’s choice (gVisor)
resources { cpu?, cpuLimit?, memoryMiB?, memoryLimitMiB? } Modal’s default
timeoutMs number, at most 24 hours Modal’s 5 minutes
createApp ({ labels }) => string | undefined always app
destroyWaitMs number 60 seconds
onDestroy ({ sandboxId, requestMs, stoppedMs }) => void
client Other ModalClient settings, such as timeoutMs

app is created on first use and holds every sandbox this provider makes; keyed names are unique within it. createApp picks a different App for one unkeyed create, for example one per job, so Modal’s per-App billing report prices each job on its own; keyed creates stay in app. list() covers app and every App the provider has created sandboxes in or prepared; in a new process, call await provider.prepareApp(name) for each App you want listed. prepareApp also takes the App lookup out of the first create that uses it, and resolves { name, appId }. Pass { createIfMissing: false } when recovering, so an App that was never created resolves null instead of being created. list() never creates the default App. listPending(labels) finds restores still tagged sandbox-sdk=pending because their creator stopped between Modal’s allocation and setup; destroy(id) stops one. image applies to fresh sandboxes only. With from, the snapshot or template supplies the file system. The first sandbox from a new image waits while Modal builds it, about a minute for node:22-bookworm; later creates take a fraction of a second. Pass size to createSandbox or resources to modal(), not both, or creation fails with invalid_argument.

Limitations

  • No pause and resume, and no terminal.
  • Snapshots keep files, not running processes.
  • Preview ports must be declared at creation.
  • At most seven labels, or six with a key, within 1024 bytes of tags in total.
  • No disk size.
  • A sandbox lives at most 24 hours.

How it works

  • Modal allows one running sandbox per name in an App, so concurrent calls with the same key share one sandbox.
  • Your labels become Modal tags. Modal allows ten; the SDK uses sandbox-sdk and sandbox-sdk-created, sandbox-sdk-key for a keyed sandbox, and keeps room for sandbox-sdk-destroying.
  • destroy() asks Modal to terminate the sandbox, tags it sandbox-sdk-destroying alongside, and returns once Modal reports it stopped, which sometimes takes about 30 seconds. A failed tag write never stops the terminate request. If Modal refuses the request (for example PERMISSION_DENIED), destroy() rejects and the sandbox stays an ordinary running sandbox. If the request fails in transport, Modal may have accepted it, so the sandbox stays tracked as terminating and destroy() polls for the stop: it resolves once Modal confirms it, and otherwise rejects with the original, retryable error. destroyWaitMs is one deadline for the terminate request and the confirmed stop, and nothing waits for the tag, so a stalled tag write or request can’t hold destroy() past it. If Modal hasn’t confirmed the stop by then, destroy() rejects with a retryable timeout; until the stop, list() and connect() still return the sandbox with state "stopped" so cleanup can find it and call destroy() again, while find() no longer hands it out for its key. The provider that asked for termination tracks it locally even if every tag write failed; another process relies on the tag, so in that case its find() can return the sandbox until Modal stops it. onDestroy receives the terminate request’s latency (null when its response was lost, or when Modal answered that the sandbox no longer exists) and the confirmed stop’s.
  • A stdin write or close that Modal refuses because the command already exited (gRPC FAILED_PRECONDITION, “Exec has already completed”) is ignored. Another FAILED_PRECONDITION is not. Any other stdin failure, such as a dropped connection, a stream reset or an error the adapter does not recognize, rejects the call and kills the command, which would otherwise run on half its input.
  • Commands run in a new session under GNU timeout, so a timeout or abort kills the whole process tree, even if this client disconnects. The default image has the needed setsid and timeout; a custom image needs them too.

Next steps

Was this page helpful?