Skip to Content
PyoDocs

Sandbox

Isolated machines on demand, for AI agents, code interpreters, previews and CI.

A sandbox is an isolated machine you create through an API. Create one, run commands, read and write files, open a port as a URL, then throw it away. Use them for:

  • AI agents that write and run code.
  • Code interpreters.
  • Previews of a branch or a change.
  • CI jobs and other code you don't trust.

Sandboxes run on your own infrastructure, so your code and data never leave it. They show in the same dashboard as your services and databases.

How sandboxes run

Sandboxes run on their own sandbox servers, outside your clusters and build servers. A sandbox server runs no k3s or Docker, just a small Pyo daemon, so a busy sandbox can't slow down your services.

On a server with KVM, each sandbox is its own microVM on Firecracker, with its own kernel. On a server without KVM, like a cloud VPS, each sandbox runs under gVisor, which gives it a kernel of its own in user space. Sandboxes never run as plain containers.

Your code asks Pyo to create a sandbox, then talks to the sandbox server directly to run commands and move files, with a short-lived token Pyo signs. Pyo isn't in the way of each command, and sandboxes keep working while Pyo itself restarts.

The sandbox server answers on your tailnet. So the code that runs commands in a sandbox, and the browser you open its terminal in, need to be on your tailnet too. Only the ports you open are on the web.

KVM or gVisor

Each time a sandbox server starts, Pyo checks what it can run:

  • Firecracker on KVM. The server has KVM and a test microVM boots in under 300 ms. This is the fastest.
  • Firecracker on nested KVM. The server is itself a VM with KVM passed through. The test boot is slower, so sandboxes start slower too.
  • gVisor. The server has no usable KVM, like most cloud VPSs, but can run gVisor.

A server with neither is turned away when it joins, with the reason. If a server loses KVM, it becomes a gVisor server at its next start. The Clusters page shows each sandbox server's runtime with a one-line summary. So do pyo sandbox servers ls and runtime in the API.

A sandbox's Isolation is Auto by default, which picks Firecracker first. VM only (isolation: "vm") never runs it on gVisor.

Which server a sandbox runs on

Pyo picks a server that's up, can run the sandbox's isolation and network, and has the memory for it. It prefers Firecracker, then a server with a snapshot of the template at that size, then the one with the most room.

To choose one yourself, pick it under Server in New sandbox, or pass server, a server's name or id, to the SDK, the API, create_sandbox in MCP or --server in the CLI. The sandbox then runs only there. If that server can't take it, Pyo says why, like "sandbox-1 has no room for 2 GB. Pick another server or a smaller size."

What gVisor can't do

Sandboxes on gVisor run the same templates and have the same commands, files, terminals, ports, network rules, limits, lifetimes and pause. These differ from Firecracker:

  • Cold starts. A sandbox starts from its template's disk in about 40 ms. Firecracker restores a running snapshot, so a template can't have a process already warm in it on gVisor.
  • Slower system calls. Each command and each process start costs more. A command takes about 5 ms instead of under 1 ms, and starting Python takes 4 to 5 times as long. For a code interpreter, keep one interpreter running and send it code.
  • Not every Linux feature. gVisor runs most programs, but some system calls and parts of /proc and /sys are missing. Docker doesn't fully work inside a sandbox, and nothing can run a VM inside one.
  • Pause needs the same gVisor release. A paused sandbox resumes only under the gVisor release it was paused under. An update that changes it ends the pauses on that server.
  • No VM only. A sandbox created with isolation: "vm" never runs on a gVisor server.
  • More disk for the server. gVisor's files take about 180 MB on the server.

Add a sandbox server

Open Sandboxes in the dashboard and choose Add a sandbox server. Team owners and admins can add one. There are two ways:

  • Cloud provider. Pyo buys a server for you and sets it up.
  • Command line. You run one command on a server you have.

Either way you need Tailscale set up in Pyo, since sandbox servers join over your tailnet.

Cloud provider

Pyo makes the server in your team's Hetzner project, the same way it makes a cluster's servers there:

  1. Pick the provider. If your team hasn't connected Hetzner yet, paste a project API token with Read & Write right there. See Make a token.
  2. Name the server, and give it an edge domain if you want sandbox ports on the web.
  3. Pick a location and a server type. Pyo reads the types, their vCPUs, memory, disk and monthly prices from Hetzner as you pick. Prices are before VAT and include the IPv4 address.
  4. Choose Create. Pyo shows the monthly price and asks once more.

The page then follows the server: Creating, Booting, Joining, Ready. On its first boot the server joins your tailnet with a single-use key, gets a one-time join code from Pyo over the tailnet and runs sandbox.sh with it. Nothing else secret is in its setup. If your tailnet has Tailnet Lock on, Pyo shows the command to sign the server. You can leave the page while it sets up. The Sandboxes page shows its progress too.

Hetzner Cloud servers have no KVM, so they run sandboxes on gVisor. Pyo puts them behind a Hetzner firewall that lets in only the web (80 and 443) and Tailscale, and they run nothing else.

From the CLI:

pyo server types --location fsn1
pyo sandbox servers create sbx-1 --location fsn1 --type cx22

Removing the server in Pyo ends its sandboxes, takes it off your tailnet and deletes it at Hetzner. Pyo shows the monthly cost that stops and asks first.

Command line

A server of your own needs:

  • Linux on x86-64 or arm64, with kernel 5.10 or newer and cgroup v2
  • KVM for Firecracker, or else root for gVisor
  • a machine of its own. A machine with k3s on it is turned away.

Choose Command line, or use the CLI:

pyo sandbox servers add sbx-1

Pyo gives you a command to run on the new machine as root. It looks like this:

curl -fsSL https://your-pyo/install/sandbox.sh | bash -s -- \
  --pyo pyo.tail1234.ts.net:5006 --server sbs_abc123 --name sbx-1 \
  --code 9f2c... --tailscale-key tskey-auth-... --version 0.4.2

It joins your tailnet, installs the daemon, Firecracker and the guest kernel, checks what the server can run and joins Pyo. A server without KVM gets gVisor too, and is checked again. The join code works once, for 15 minutes. When it expires, the dashboard says This command expired. Choose Get a new command for a fresh one, and the old one stops working.

The server's daemon answers only on your tailnet. Only ports 80 and 443 are public, for the edge proxy that serves sandbox ports.

Sandbox servers show on the Clusters page as their own group, with their runtime, CPUs, memory, disk and sandboxes.

How the files are checked

The sandbox server's files come with each Pyo release. Before anything changes on the server, sandbox.sh checks the release's release.json against its Sigstore signature, as the installer does. Then it checks the files against the SHA-256 that release.json lists for that architecture in its sandbox field, and gVisor's files against its sandboxGvisor field. gVisor is a pinned release, checked against its own SHA-512 when Pyo's release is made. If anything doesn't match, nothing is installed.

sandbox.sh options

The dashboard fills in the options that join the server. These change how it installs:

OptionWhat it does
--version XThe Pyo release whose sandbox files to install, like 0.4.2.
--bundle FILESandbox files from a file or URL instead of the release. Also PYO_SANDBOX_BUNDLE. They're checked against --bundle-sha256, or else against the signed release.json of --version.
--bundle-sha256 SUMThe SHA-256 to check --bundle against. Also PYO_SANDBOX_BUNDLE_SHA256.
--gvisor-bundle XgVisor's files from a file or URL instead of the release, for a server without KVM. Also PYO_SANDBOX_GVISOR_BUNDLE. They're checked against the signed release.json of --version.
--devSkip the check, for files you built yourself. Also PYO_SANDBOX_DEV=1.
--edge-domain DServe sandbox ports at <port>-<sandbox>.D on ports 80 and 443. Also PYO_SANDBOX_EDGE_DOMAIN. See Edge domain.
--edge-cert FILEThe certificate for *.D, as PEM with the full chain. Default /etc/pyo-sandbox/edge/cert.pem.
--edge-key FILEIts private key. Default /etc/pyo-sandbox/edge/key.pem.

To update the daemon, run the command again with a newer --version. A server that has joined needs no code then, and running sandboxes keep running. A gVisor server gets the release's gVisor too.

To take Pyo off the server, remove it on the Clusters page or with pyo sandbox servers rm, then run this on it:

curl -fsSL https://your-pyo/install/sandbox.sh | bash -s -- --uninstall

Its sandboxes end. Tailscale stays.

Edge domain

Opened ports are served by the sandbox server's edge proxy, at https://<port>-<sandbox>.<edge domain>, like https://3000-sbx-abc.sbx.example.com. Give a server an edge domain when you add it, under Edge domain, or with --edge-domain. Without one, ports can't be opened on that server.

The edge domain needs a wildcard DNS record, *.sbx.example.com, pointing at the server's public address. HTTPS needs a wildcard certificate for it.

With Cloudflare

When your Cloudflare connection can edit the domain's zone, the server's menu on the Clusters page offers:

  • Create DNS record, which adds the wildcard record pointing at the server's public addresses, not proxied. A record already on that name is never changed.
  • Get certificate, which gets a wildcard certificate from Let's Encrypt and puts it on the server. Pyo renews it 30 days before it runs out. Renew certificate renews it now.

Pyo gets the certificate itself, so your Cloudflare token never goes to the sandbox server.

Your own certificate

Without Cloudflare, put a wildcard certificate on the server yourself, at /etc/pyo-sandbox/edge/cert.pem and /etc/pyo-sandbox/edge/key.pem, or the paths you gave with --edge-cert and --edge-key. The edge serves it within a minute, with no restart. Until there's a certificate, ports are served over plain HTTP.

Templates

A sandbox starts from a sandbox template, made from a container image. Find them under Sandbox templates, in the sidebar's Sandboxes menu.

The base template

Every Pyo has base, a template Pyo makes for you. A sandbox starts from it when you don't name a template, and New sandbox picks it first. It's listed under Sandbox templates from the start, even before you add a sandbox server.

It's Ubuntu 24.04 LTS with the tools coding agents expect:

  • System: git, curl, wget, jq, ripgrep, zip, unzip, rsync, openssh-client, sudo, vim, nano and the usual network tools.
  • Build tools: build-essential, pkg-config, cmake and ninja.
  • Python: Python 3.12 with pip, venv and uv.
  • JavaScript: Node.js 24 LTS with npm, pnpm, Bun and Deno.
  • CLIs: GitHub's gh and the Docker CLI with buildx and compose. There's no Docker daemon in it, so point DOCKER_HOST at one.
  • Coding agents: Claude Code, Codex and opencode.

Commands run as root in /root. pip installs into the system Python, since a sandbox is thrown away. The full list with versions is in pyo-sandbox-images.

base belongs to the installation, so every team has it. It can't be deleted, and no other template can be named base.

The desktop template

desktop is base with a desktop and a browser, for agents that use a browser and for people who want to watch them. Its sandboxes get 2 CPUs and 2 GiB of memory unless you ask for more.

  • The screen: a desktop you watch and use in your browser, served by voxl on port 6080 inside the sandbox. Choose Desktop in the sandboxes list or Open desktop on the sandbox's page. It opens over HTTPS at sandboxes.<tailnet>.ts.net, which Pyo passes on to the sandbox server, so it needs Tailscale set up in Pyo. Until then, Open desktop is greyed out.
  • The browser: Google Chrome on x86-64 and Chromium on arm64. Drive it over the Chrome DevTools Protocol at 127.0.0.1:9222 inside the sandbox, with Playwright or Puppeteer. Browser in the sandboxes list opens the screen with the browser in front.

Nothing starts until it's used: the first look at the screen or the first CDP connection starts the desktop, then the browser.

pyo sandbox create desktop

Like base, it belongs to the installation and can't be deleted.

On first use

A sandbox server doesn't get base or desktop when it joins. It makes each the first time a sandbox needs it there: it downloads the image, about 0.9 GB for base and 1.25 GB for desktop, then unpacks it and boots it once. The create waits for that and then starts the sandbox, so the first sandbox from it on a server takes longer. Later ones on that server start at once.

While it waits, the dashboard says Getting base ready on sandbox-1… with how far it got, and the templates list shows each server's progress. Two sandboxes created at once on that server wait for the same download. The templates page says base is Ready to use and lists the servers that have it.

If a server isn't done after 4 minutes, the create stops with "base is still getting ready on sandbox-1. Try again in a minute." The server keeps going, so the next try starts once it's done.

How base and desktop update

Their images come from pyo-sandbox-images, ghcr.io/upsetdev/pyo-sandbox-images/base and ghcr.io/upsetdev/pyo-sandbox-images/desktop. They're rebuilt every week with Ubuntu's security updates. Each build is signed, and so is the list of its images, images.json, which names each image by digest.

Pyo reads the latest images.json from GitHub every hour and uses it only when its signature checks out. Each Pyo release also carries the one of when it was made, so a Pyo that can't reach GitHub still has images. PYO_UPDATE_CHECK=off stops the hourly check too. When a newer build comes out:

  • Each sandbox server that has the template makes the new one in the background. Servers that never used it wait for their first sandbox from it.
  • New sandboxes start from it once it's ready on their server. Until then they start from the one before.
  • Running and paused sandboxes keep the one they started from. The server deletes it once no sandbox uses it.

A template never moves back to an older build.

Your own templates

Make a template from any image:

pyo sandbox templates create node-22 node:22

The image can be public on any registry, or in Pyo's registry. Every sandbox server that may use the template pulls the image and unpacks it. A Firecracker server then boots it once and saves a snapshot to start sandboxes from. A gVisor server starts each sandbox from the unpacked disk. A template is ready once one server has it. Each template shows its state on each server: pending, building (pulling, unpacking or snapshotting), ready or failed, with its size once ready.

To add your own tools to base, build on its image and push the result to Pyo's registry:

FROM ghcr.io/upsetdev/pyo-sandbox-images/base:24.04
RUN apt-get update && apt-get install -y --no-install-recommends postgresql-client \
 && rm -rf /var/lib/apt/lists/*
RUN uv pip install --system pandas

Pyo doesn't use an image's USER, ENV or WORKDIR yet. Commands run as root in /root, with PATH set to the usual system folders, so put tools in /usr/local/bin or /usr/bin.

An image may take up to 10 GiB, and the server needs the disk space to unpack it. A server builds one template at a time.

Templates belong to your team, or to the installation, which every team can use. Deleting a template removes it from the servers that made it.

Networking

A sandbox has the internet by default. Choose No network (network: "none") for a sandbox with no network at all. Opened ports still work then, since the edge reaches them through the sandbox server, not the network.

A sandbox with network can't reach:

  • the sandbox server itself, on any of its addresses
  • your tailnet
  • other sandboxes
  • private and link-local ranges, like 10.0.0.0/8, 192.168.0.0/16 and 169.254.169.254
  • anything over IPv6

DNS goes to 1.1.1.1 and 8.8.8.8. Nothing from outside can open a connection into a sandbox. Only replies come back.

Sandboxes get addresses from 198.18.0.0/16, a range nothing routes. If that overlaps the server's own networks, the daemon won't turn networking on. To change the range or the DNS servers, or to block more ranges, edit /etc/pyo-sandbox/local.json on the server and restart pyo-sandbox.

Docker and ufw on the server

Docker and ufw set the server's forwarding policy to drop. When it is, the daemon adds two rules of its own, to DOCKER-USER when Docker made it, or else to FORWARD, so sandbox traffic gets out and its replies come back. It never changes the policy itself. With ufw active, sandbox.sh also opens the daemon's port on tailscale0, and ports 80 and 443 for the edge. Any other firewall in front of the server needs 80 and 443 open too.

Limits

Each sandbox can have:

DefaultRange
CPUs11 to 32
Memory512 MiB128 MiB to 64 GiB
Disk2 GiB64 MiB to 256 GiB
Lifetime5 minutesup to 365 days, or no limit

A sandbox ends when its lifetime runs out. Extend it while it runs. A sandbox with no limit (ttl: "none") runs until you delete it.

Each team also has limits on all its sandboxes together. Paused ones count.

LimitDefault
Sandboxes at once10
CPUs16
Memory16 GiB
Disk100 GiB
Longest lifetime1 day

The installation's admin changes them in the team's Settings, under Sandboxes. Setting Sandboxes at once to 0 turns sandboxes off for the team. Longest lifetime can be up to 365 days, or No limit, which lets the team's sandboxes run until they're deleted.

Names

Every sandbox has a name, to tell it apart from the others and find it. Give one when you create it, like checkout tests, of up to 63 letters, digits, spaces, dashes, underscores and dots. Without one, Pyo makes up a short one like quiet-river.

Names don't have to be unique, and they never address a sandbox: its id does. So renaming one breaks nothing. Rename a sandbox from its name on its page, with pyo sandbox rename, with rename_sandbox in MCP, or with a PATCH in the API. The sandboxes list searches by name or id.

Use sandboxes

An API key needs Sandboxes or Full access to use sandboxes. Sandboxes access can read, and create and use sandboxes, but change nothing else.

TypeScript SDK

Install @pyodev/sandbox:

npm install @pyodev/sandbox

It reads PYO_URL, PYO_API_KEY and PYO_TEAM from the environment, or takes them as options. It works in Node 20 and later, and in Bun.

import { Sandbox } from "@pyodev/sandbox";

// From base. Pass template to start from another one, and server to pick the server.
const sbx = await Sandbox.create({ ttl: "1h" });

// Commands
const r = await sbx.exec("node -v");
console.log(r.stdout, r.exitCode);

// Files
await sbx.files.write("/app/index.js", "console.log('hi')");
const text = await sbx.files.read("/app/index.js");

// A terminal
const pty = await sbx.pty({ cols: 120, rows: 30, onData: (b) => process.stdout.write(b) });
pty.write("ls\r");

// Ports
await sbx.spawn("npx serve -l 3000");
const url = await sbx.ports.open(3000);

await sbx.delete();
  • Commands: exec waits for a command and returns its output and exit code. A command times out after 60 seconds unless you set timeoutMs, and keeps up to 8 MiB of each output. spawn starts one and returns at once, for servers and interactive input.
  • Files: read, write, list, stat and remove files. Each call moves up to 64 MiB.
  • Terminals: pty opens a terminal, with resize.
  • Ports: ports.open returns the port's URL on the edge. A private port, with { public: false }, needs the sandbox token on each request. ports.connect opens a TCP connection to a port inside the sandbox, even with no network.
  • Lifetime: extend, pause, resume and delete. A paused sandbox keeps its memory and files and resumes where it was.
  • Servers: Sandbox.servers() lists the team's sandbox servers, each with its runtime, firecracker or gvisor.

The token for the sandbox server lasts an hour. The SDK gets a new one from Pyo five minutes before it runs out. To use a sandbox from a browser without an API key, your backend passes on sbx.connection() and refreshes the token for it.

The SDK also has ready-made tools for the Claude API and the Vercel AI SDK. See its README for every option.

MCP

Once your team can use a sandbox server, MCP gets sandbox tools, so an assistant can run code for you in a sandbox. Give the assistant Sandboxes or Full access.

ToolWhat it does
create_sandboxCreates a sandbox, from base unless the assistant names a template, on the server it names or one Pyo picks, and returns its id
rename_sandboxGives a sandbox another name
run_codeRuns Python, Node or Bash code and returns its output
execRuns a shell command
read_file and write_fileRead and write a file
open_port and close_portServe a port at a URL, or stop serving it
pause_sandboxPauses a sandbox
delete_sandboxEnds a sandbox and throws away its files

These go through Pyo, so the assistant doesn't need your tailnet. See the full tool list.

CLI

The pyo CLI has pyo sandbox:

pyo sandbox create --name checkout-tests --ttl 30m
pyo sandbox exec sbx_abc123 "node -v"
pyo sandbox shell sbx_abc123
pyo sandbox cp ./app.js sbx_abc123:/app/app.js
pyo sandbox ports open sbx_abc123 3000
pyo sandbox rm sbx_abc123

pyo sandbox create starts from base. Name a template to start from another one, like pyo sandbox create node-22, and pick the server with --server sandbox-1. --ttl takes a lifetime like 30m, 6h or 7d, or none to keep it until you delete it. It also has ls, get, rename, pause, resume, extend and token, and servers and templates to manage those. exec, shell and cp reach the sandbox server directly, so they need your tailnet. See the command reference.

Dashboard

The Sandboxes page lists your sandboxes by name, with a search. A running sandbox has Terminal right in the list, and a desktop sandbox has Desktop and Browser too. New sandbox creates one, and shows the same choices as SDK code, ready to copy. Its Server field is Any server by default, and lists each server with its runtime and free memory. Its Lifetime goes from 5 minutes up to the team's longest, or No limit when the team allows it. Sandbox templates has a Use button on each template that opens New sandbox on it. A sandbox's page has its Overview with its ports, a Terminal, its Files, the Commands it ran and its Metrics.

Planned

These aren't in Pyo yet:

  • Templates from a Git repository or a Dockerfile.
  • Pausing a sandbox on its own when it's idle.
  • Allow and deny lists for a sandbox's outgoing traffic.
  • A Python SDK.
  • Promote a sandbox to a service, with a domain, HTTPS and autoscaling.

On this page

Edit page