Code sandboxes

sandbox runs code you didn't write, from a user or a model, outside your app's process, with no secrets, files or network unless you allow them, and stops it at its limits.

Vercel Sandbox and E2B run it in microVMs in production; local runs a limited subprocess for development.

sandbox:
  driver: vercel-sandbox
  limits: { timeout: 30s, memory: 512MB, output: 1MB, max-cost: $0.05 }
  network: [pypi.org]

import { sandbox } from "mainsdk";

const out = await sandbox.run({
  code: "print(sum(range(10)))",
  language: "python",
  feature: "analysis",        // no network, no secrets, killed at its limits
});

sandbox:
  driver: vercel-sandbox

Quick start

sandbox:
  driver: local                      # vercel-sandbox | e2b | local (development only)
  local: { python: python3 }
permissions:
  processes: [python3]               # the local driver starts code through the system interface
  disk: { temp: { max: 1GB } }       # and works in a temp folder it removes afterwards

import { sandbox } from "mainsdk";

export async function runSnippet(code: string) {
  const out = await sandbox.run({ code, language: "python", feature: "notebook" });
  return out.stop ? `stopped: ${out.stop}` : out.stdout;
}

language is python, node or bash. feature names the run in the audit event. A run that is stopped still returns a result with stop set; it does not throw.

Configuration

sandbox:
  driver: vercel-sandbox
  limits: { timeout: 30s, memory: 512MB, output: 1MB, files: 50MB, max-cost: $0.05 }
  network: [pypi.org]                # the most any run may get; must also be in network.allow
  secrets: [OPENWEATHER_KEY]         # the only secrets a run may be given
  vercel: { token: "secret:VERCEL_TOKEN", project: prj_123 }
network:
  allow: [pypi.org]

An unknown key under sandbox is refused at load with the key named. The provider's API host is added to the network list for you.

What you get

• Code never runs in your app's process, and starts with an empty environment, an empty /work holding only the files you pass, and an empty /out.
• No network by default. Each host you give must be in both sandbox.network and network.allow, or the call fails before anything runs.
• Output is cut at limits.output and redacted for secret values and known key formats (it comes back as [redacted:secret]).
• The worst-case cost (price per second times the timeout) is checked against maxCost and limits.max-cost before the run starts.
• One audit event per run with the SHA-256 of the code, driver, isolation, duration, exit code, stop reason, hosts and env names. Never the code, output or secret values.
• A provider outage fails only sandbox calls (MAIN-SANDBOX-0006), not the rest of your app.

Examples

Pass files in and read results out

Files you pass appear in the code's working folder (/work); files it writes to the out folder next to it (../out/ on the local driver) come back as FileRefs owned by the caller.

import { sandbox } from "mainsdk";

export async function chart(csv: string) {
  const out = await sandbox.run({
    language: "python",
    feature: "chart",
    files: { "data.csv": csv },
    code: "rows = open('data.csv').read().splitlines()\nopen('../out/count.txt', 'w').write(str(len(rows)))",
  });
  return out.files;   // [{ id, ... }] for count.txt
}

Give a run one secret and one host

import { sandbox, secret } from "mainsdk";

export function weather(code: string) {
  return sandbox.run({
    code,
    language: "python",
    feature: "weather",
    network: ["pypi.org"],
    env: { WEATHER_KEY: secret("OPENWEATHER_KEY") },
  });
}

A name that isn't under sandbox.secrets fails with MAIN-SANDBOX-0009 and nothing runs.

Keep a session open across commands

A session is scoped to the tenant that created it, closes after idle (5 minutes by default), and runs commands as a program and an argument array, never through a shell.

import { sandbox } from "mainsdk";

export async function twoSteps() {
  const session = await sandbox.create({ feature: "notebook", idle: "1m" });
  try {
    await session.write("a.txt", "hello");
    const out = await session.run("python3", ["-c", "print(open('a.txt').read())"]);
    return out.stdout;
  } finally {
    await session.close();
  }
}

sandbox.get(id) returns an open session of the current tenant.

Let an agent run code

sandbox.action returns a code-runner action. Its input is { code, language, files? }, its risk is write unless you set it, and an agent calling it passes the agent's budget and approval rules. Its cost counts against the agent's budget.

import { ai, sandbox } from "mainsdk";

const runPython = sandbox.action({
  name: "code.run",
  intent: "Run Python to analyse the user's data",
  languages: ["python"],
});

export function analyse(user: { id: string; roles: string[] }, goal: string) {
  return ai.run({ model: "anthropic/claude-sonnet-4-5", feature: "analysis", agent: "analyst", user, goal, tools: [ai.tool(runPython)] });
}

Reference

Most apps use the sandbox export, which main.yaml builds for you. These are the pieces underneath, for tests and custom wiring.

Isolation you can read

Every result has isolation: microvm for the providers, namespace for the local driver on Linux with an empty network, and weak for the local driver otherwise (a proxy refuses other hosts; the code is not in a separate network). Treat weak as a development convenience.

Errors and checks

mainsdk check reports MAIN-SANDBOX-0010 for eval, new Function or vm.* on anything but a string literal, MAIN-SANDBOX-0011 for the local driver in production, and MAIN-SANDBOX-0012 for a sandbox.network host missing from network.allow. See check codes.

Swapping drivers

Change sandbox.driver and nothing in your code changes: vercel-sandbox and e2b run code in microVMs through the provider's API (token or key as a secret reference), and local runs a subprocess for development. Every driver gets the same limits, the same network allowlist (enforced through the provider's egress policy) and the same audit event. local in production fails mainsdk check --env prod with MAIN-SANDBOX-0011.

Testing

The local driver needs no account; run the real code in a test and assert on stdout, stop and files. Put the interpreters under permissions.processes in the test's main.yaml. The provider drivers are covered by the conformance suite on recorded sessions.

Security and privacy

• Code never runs in your app's process.
• Secrets reach a run only when listed under sandbox.secrets and passed by name; the audit event records names, never values.
• Every run is audited with the SHA-256 of the code, never the code or its output.
• Sessions of one tenant can't be reached from another.

Next

• Network permissions
• Actions and agent tools
• Server facts and programs