English
Docs menu

Agent Sandboxes docs · Start

How Pethost Agent Sandboxes work

Updated · 8 min read

A sandbox is a Linux VM that your code or your agent starts in about 0.15 s, uses through an API, and leaves alone. When nothing happens in it, it pauses with its memory and processes, and later stops with only its disk. The next call wakes it where it was. This page is the model: what a sandbox is, its three states, what moves it between them, and where each byte lives.

In short
  • A microVM per sandbox: Firecracker, its own kernel, root inside, Ubuntu with Python, Node.js, Docker, three coding agents and Chrome.
  • Three states: RUNNING in its server's memory, PAUSED on its server's disk with memory and processes kept, STOPPED in object storage with its disk alone.
  • Wake on use: any call into a paused sandbox, an SSH login or a request to one of its ports resumes it in about 0.1 s.
  • Two APIs: the panel keeps the record of each sandbox, and the sandbox's own server runs what happens inside it. The SDKs and the CLI hide the difference.
  • Billed by the second for each state: billing.

What a sandbox is

A sandbox is one virtual machine, made from a template. Inside it you are root, and commands run as the user user, who has passwordless sudo, in /home/user. Its hostname is its id: 16 characters, lower-case letters and digits.

Our template, base, holds Ubuntu 24.04 with build tools and git, Python 3, Node.js 22, Docker, the coding agents Claude Code, Codex and OpenCode, and a desktop with Google Chrome. Two of these start only when first used, and cost nothing until then: the desktop, at the first screenshot or desktop link (some seconds), and Docker's daemon, at the first connection to /var/run/docker.sock.

Isolation: a Firecracker microVM each

Every sandbox is its own Firecracker microVM, with its own Linux kernel. Firecracker runs each VM inside its jailer: its own chroot, an unprivileged user, a cgroup, a seccomp filter and its own network namespace. The guest is yours, root and kernel included; the host decides what it gets.

  • Its size is held by the host. A VM gets its size's vCPUs and memory from the server, and nothing the guest says changes that.
  • Its own identity. Each sandbox gets fresh kernel randomness, its own hostname and its own machine-id, even when it starts from the same snapshot as another.
  • No secrets inside. The workspace's secrets never enter a VM, and neither do API tokens: a sandbox is reached with a token for that one sandbox, which expires.

Sizes

A sandbox is one of four sizes, for its VM's whole life:

SizevCPUsMemoryDisk
SMALL24 GiB10 GiB
DEFAULT48 GiB20 GiB
LARGE816 GiB40 GiB
XLARGE1632 GiB80 GiB

The disk is what the sandbox may write: the template's own files do not count against it. A new size (UpdateSandbox) restarts a RUNNING sandbox in a VM of that size, its files kept and its processes ended; a STOPPED one takes the new size at its next start, and a PAUSED one must be resumed or stopped first. A new size keeps the disk unless you set grow_disk, which grows it to the new size's. A disk never shrinks.

Templates

A template is the files a sandbox starts with. Ours is base, rebuilt every month and at once for a security fix. Yours is a sandbox's disk saved with CreateTemplate: its files, the packages you installed and its Docker images. A template keeps no memory, no processes and no agent conversations: a sandbox made from it boots fresh.

Each save is a new version, name@1, name@2, and a sandbox started from name takes the newest. Every server starts sandboxes from any version. A version's min_size is the smallest size whose disk holds what it saved. A sandbox from your own template starts in about 0.22 s once its server holds the version; the first on each server fetches it, about 10 s a GiB: templates.

Two APIs: the panel and the sandbox's server

Two services answer, by what they know:

  • SandboxService is the panel, at https://console.pethost.dev, called with your API token. It holds the workspace and each sandbox as a record: create, settings, pause, resume, fork, delete, templates, volumes, events and usage.
  • SandboxRuntimeService is the sandbox's own server, at the url of its connection, called with a connection token for that one sandbox. It runs what happens inside: commands, files, the desktop, coding agents and links.

The SDKs and the CLI connect for you: run_command is one call, and the SDK finds the server and keeps the token fresh. Runtime calls go straight to the server, so the panel is never in the path of what runs inside a sandbox, and a server runs its sandboxes without the panel.

The three states

RUNNING

In its server's memory

Runs your processes and answers every call.

$0.036 an hour, DEFAULT

Idle 5 min, or PauseSandbox

Any call, SSH login or port request, in about 0.1 s

PAUSED

On its server's disk

Keeps memory, processes and disk, and its place on the server.

$0.0108 an hour, DEFAULT

Idle 30 min, or StopSandbox

STOPPED

In object storage

Keeps its disk; its processes end.

$0.03 a GiB a month of its own data

ResumeSandbox boots it again: about 0.2 s with its disk on the server, about 10 s a GiB from object storage

The default timers, from the last thing that happened in the sandbox. A RUNNING sandbox can also stop at once, and any sandbox can be deleted.
StateWhere it livesWhat it keepsHow it wakes
RUNNINGIts server's memoryEverything, runningIt is awake
PAUSEDIts server's diskMemory, processes, diskAt the next call, SSH login or port request, in about 0.1 s; never refused for room
STOPPEDObject storage, and its server's disk while there is roomIts diskBy ResumeSandbox, or like a paused one with wake_when_stopped
DELETEDNowhereIts record for 30 days, its events and metrics for a dayNever

Why PAUSED exists

An agent's VM spends most of its time waiting: for the model to think, for a person to read the answer, for the next message. Stopping it ends its processes, and with them the dev server, the REPL, the shell's state and the open browser the agent was using. Keeping it RUNNING pays the full price for waiting.

PAUSED keeps everything, memory and processes included, for 30% of the running price, and the server keeps the sandbox's place, so a resume is never refused for room. Your code does nothing to wake it: the next call into the sandbox resumes it first, in about 0.1 s, and the call then runs as if the sandbox had never stopped. A paused sandbox takes 41 ms on its server to resume, and a command sent to one answers in about 80 ms.

What moves a sandbox

FromToWhat moves it
RUNNINGPAUSEDIts pause timer; PauseSandbox; its server short of memory, once it has been idle a minute; its server's machine restarting (MAINTENANCE, which counts nothing)
PAUSEDRUNNINGAny runtime call, an SSH login or a request to a port (WAKE); ResumeSandbox
RUNNING or PAUSEDSTOPPEDIts stop timer; StopSandbox; its server short of disk (a paused one); a workspace with nothing to pay (UNPAID); a crash of its VM or its server (CRASH)
STOPPEDRUNNINGResumeSandbox; a call, SSH login or port request only with wake_when_stopped, and never after a CRASH
AnyDELETEDDeleteSandbox; its delete timer; the loss of its server, for a sandbox with no copy in object storage

Each change has a reason, state_reason, and words for people, state_message. Lifecycle and idle says what counts as activity and how to set the timers.

What wakes a sandbox

Any call of SandboxRuntimeService, an SSH login or a request to one of its ports first resumes a PAUSED sandbox, on its own server. A STOPPED sandbox wakes that way only when its lifecycle says wake_when_stopped. Without it:

  • a runtime call answers FAILED_PRECONDITION with the detail Stopped;
  • a request to a port answers HTTP 503, “stopped: resume it”;
  • only ResumeSandbox starts it.

A sandbox stopped by a CRASH starts again only by ResumeSandbox. While a stopped sandbox's disk is fetched back from object storage, calls into it answer UNAVAILABLE with Restoring, and ResumeSandbox waits up to 45 s, then says how far the fetch is (Sandbox.restore).

Where your data lives

WhatPauseStopForkTemplateDelete
MemoryKeptLostCopiedNot savedGone
Running processesKeptEndedCopied, runningNot savedGone
Files and Docker imagesKeptKeptCopiedSavedGone
Agent conversationsKeptKeptCopiedNot savedGone

A stopped sandbox's disk is copied to object storage in the EU a minute after it stops, in chunks encrypted with a key for that one sandbox; memory is never copied there. Its server keeps its own copy while it has room. A volume is different: it lives on one server's disk and is not copied anywhere, so keep what must survive the loss of a server somewhere else too.

Moves and lost servers

A STOPPED sandbox with a current copy and no volume starts on another server when its own has no room for it, and its addresses move with it: the connection's url, its ports' URLs and its ssh_command. A PAUSED sandbox never moves: it resumes on the server that holds its memory.

If a server is lost, each of its sandboxes with a copy becomes STOPPED from its last copy and starts on another server at its next ResumeSandbox. A sandbox with no copy is deleted, and so are the volumes on that server.

Questions

Is a sandbox a container?

No. Each sandbox is a Firecracker microVM with its own Linux kernel, and you are root inside it. You can run Docker containers inside a sandbox.

What happens to my processes when a sandbox pauses?

They stop where they are and keep their memory, open files and state. The next call, SSH login or request to a port resumes them in about 0.1 s, as if nothing had happened.

Can a paused sandbox fail to wake for lack of room?

No. Its server keeps its place while it is paused, so a resume is never refused for room. A stopped sandbox can be: then ResumeSandbox may start it on another server.

Where are my files when a sandbox is stopped?

On its disk, copied to object storage in the EU, encrypted with a key for that sandbox, and on its server while there is room. They come back as they were when it resumes.

Does a template keep running processes?

No. A template saves the disk only: files, packages and Docker images. A sandbox made from it boots fresh, with no process and no agent conversation of the one it was saved from. To copy a running sandbox, fork it.

Try Pethost Agent Sandboxes

A 7-day trial with $1 of usage and 4 vCPUs, with a card. Then a plan from $20 a month, which includes as much usage.

Start the trial