# Sandbox (/docs/build/sandbox)



Give an agent an isolated computer with `sandbox()`:

```ts
import { Agent, sandbox } from "@nylorun/agents";

export const analyst = Agent({
  id: "analyst",
  instructions: "Analyse the data the user gives you. Use Python.",
}).use(sandbox());
```

The model gets `bash`, `read`, `write`, `edit`, `grep`, and `glob` on a Linux
machine with a persistent `/workspace`. These tools run in the Runtime, not in
your process, so sandbox-only agents need no connected executor. The agent
declares what it needs; the Runtime decides where it runs.

Every option is optional plain data:

```ts
.use(sandbox({
  image: "python:3.13",
  network: { preset: "dev", allow: ["api.example.com"] },
  resources: { cpus: 2, memory: "2GiB" },
  idle: "15m",
}))
```

| Option                      | Default                              | Meaning                                            |
| --------------------------- | ------------------------------------ | -------------------------------------------------- |
| `image`                     | Runtime default (`python:3.13-slim`) | Any OCI image.                                     |
| `network.preset`            | `"dev"`                              | `"none"`, `"dev"`, or `"open"`.                    |
| `network.allow`             | —                                    | Extra hosts, for example `api.example.com`.        |
| `resources.cpus` / `memory` | Runtime default                      | Compute budget. Memory is a size such as `"2GiB"`. |
| `idle`                      | Runtime default                      | Stop compute when idle; files persist.             |

The `dev` preset allows package registries and code hosts. Private networks,
loopback, the host, and cloud metadata endpoints are always blocked. Options
from the full design that are not in this version (`setup`, `files`, `secrets`,
`mount`, `onStart`, `scope`, …) throw a `SandboxError` that says so.

Runtime owns one virtual sandbox per session, created on the first sandbox tool
call and reattached with its files after idle stops or restarts. The backend is
an emulated shell in the Runtime process, not a VM security boundary. Set
`NYLORUN_SANDBOX=auto` or `virtual`; both select the virtual backend.
`GET /v1/tenant/sandbox` and `nylo doctor sandbox` report it.

Tool calls emit `sandbox.state` and `sandbox.exec` session events. A sandbox
call interrupted by a crash becomes uncertain and is never re-run. Virtual
workspaces live in the Tenant's `sandboxes/` directory.

Pass `{ id: "…" }` as the second argument to override the default capability id
`"sandbox"`. An agent may declare only one sandbox capability.

## Next step [#next-step]

<Cards>
  <Card title="Skills" description="Load an Agent Skills catalog." href="/docs/build/skills" />

  <Card title="Run" description="Start Runtime and inspect sandbox status." href="/docs/run" />
</Cards>