# Sandboxes

> Run untrusted or generated code in isolated containers.

```bash title="Run in your project folder"
npx extraorbital add sandbox
```

A sandbox resource is a place to run code you do not want on your own servers: an agent's
generated code, a user's script, a build. You get a token for the official Modal SDK; your code
starts sandboxes, runs commands in them and reads their output directly. Nothing goes through
ExtraOrbital.

Run the command → read the credentials in .env → connect your app through the SDK or API.

## Limits

| Limit | Free · Prototype | Paid |
| --- | --- | --- |
| Sandbox resources | 10 | No plan count cap |
| Compute | From the $5.00 account allowance | $0.1419 / core-hour, $0.024 / GiB-hour |
| Bandwidth | From the $5.00 account allowance | $0.04 / GiB of egress |
| Spend | Idle environments are free | Shared team credit or budget |

Free allowances are shared across the account. Provider limits still apply on paid plans.

<span id="run-code-in-a-sandbox" />

## Use it

```js
import { ModalClient } from "modal";

const modal = new ModalClient();
const app = await modal.apps.fromName("my-app", { createIfMissing: true });
const sandbox = await modal.sandboxes.create(app, modal.images.fromRegistry("python:3.12-slim"));
const run = await sandbox.exec(["python", "-c", "print(2 + 2)"]);
console.log(await run.stdout.readText());
await sandbox.terminate();
```

The token runs code that you pay for: keep it server-side. Each machine and each deploy target
gets a credential of its own.

## Environment variables

The CLI writes these to `.env` or an existing `.env.local`. The Modal SDKs (TypeScript, Python
and Go) read them as they are.

| Variable | Purpose |
| --- | --- |
| `MODAL_TOKEN_ID` | Identifies the credential |
| `MODAL_TOKEN_SECRET` | Authenticates it; keep it private |
| `MODAL_ENVIRONMENT` | The resource's environment, where every sandbox and app of the resource runs |

## Specifics

### Budget

Set a spending ceiling per calendar month (UTC) with `maxBudgetCents`. Past it, running sandboxes
stop and new ones are refused until the next month or a higher ceiling. Spend is read a few
minutes late, so a resource can pass its ceiling by what it spends in that time.

### Read-only credentials

A `read` credential lists and reads what runs in the environment and cannot start anything.

### GPUs and public URLs

GPUs are off by default. Web endpoints need Modal's proxy authentication: an environment refuses
unauthenticated web endpoints. Use sandboxes for code you run, not to host public sites.

### Extra environments

A resource is one environment. An environment created with a resource's credential is removed
within a minute, and what ran in it is billed to that resource. Add another resource for another
environment.

### Freeze

Freezing a resource stops every sandbox and app in it and refuses its credentials within a few
seconds. Unfreezing gives the same credentials back; deploy stopped apps again.

<span id="usage" />

## Pricing

| Usage | Paid rate |
| --- | --- |
| Compute | $0.1419 / core-hour, $0.024 / GiB-hour |
| Bandwidth | $0.04 / GiB of egress |
| Spend | Idle environments are free |

See [plans and billing](/pricing) for subscription fees and billing terms.

---

More for agents: [Sitemap](https://extraorbital.dev/sitemap.md) · [llms.txt](https://extraorbital.dev/llms.txt) · [agents.md](https://extraorbital.dev/agents.md)
