Sandbox
Give an agent Runtime-executed computer tools on an isolated machine.
Give an agent an isolated computer with sandbox():
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:
.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 each sandbox: one per session, created on the first sandbox tool
call, stopped after its idle timeout, and reattached with its files on the next
call, including after a restart. On first use the Runtime probes backends in
order and keeps the choice for its lifetime: a microsandbox microVM (macOS on
Apple Silicon, or Linux with /dev/kvm), then the in-process virtual shell
(just-bash). Set NYLORUN_SANDBOX=microsandbox or virtual to force one; a
forced backend never falls back. GET /v1/host/sandbox and
nylorun doctor sandbox report the selection.
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 sandboxes/ beside the SQLite file.
Pass { id: "…" } as the second argument to override the default capability id
"sandbox". An agent may declare only one sandbox capability.