---
title: "How Pethost Agent Sandboxes work | Pethost Agent Sandboxes"
description: "What a sandbox is, its three states RUNNING, PAUSED and STOPPED, what wakes it, the two APIs, and where its memory, processes and files live."
---

[Agent Sandboxes docs](https://pethost.dev/docs/sandboxes/) · Start

# How Pethost Agent Sandboxes work

Updated 21 November 2026 · 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](https://pethost.dev/docs/sandboxes/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:

| Size | vCPUs | Memory | Disk |
| --- | --- | --- | --- |
| SMALL | 2 | 4 GiB | 10 GiB |
| DEFAULT | 4 | 8 GiB | 20 GiB |
| LARGE | 8 | 16 GiB | 40 GiB |
| XLARGE | 16 | 32 GiB | 80 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](https://pethost.dev/docs/sandboxes/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.

| State | Where it lives | What it keeps | How it wakes |
| --- | --- | --- | --- |
| RUNNING | Its server's memory | Everything, running | It is awake |
| PAUSED | Its server's disk | Memory, processes, disk | At the next call, SSH login or port request, in about 0.1 s; never refused for room |
| STOPPED | Object storage, and its server's disk while there is room | Its disk | By `ResumeSandbox`, or like a paused one with `wake_when_stopped` |
| DELETED | Nowhere | Its record for 30 days, its events and metrics for a day | Never |

## 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

| From | To | What moves it |
| --- | --- | --- |
| RUNNING | PAUSED | Its pause timer; `PauseSandbox`; its server short of memory, once it has been idle a minute; its server's machine restarting (MAINTENANCE, which counts nothing) |
| PAUSED | RUNNING | Any runtime call, an SSH login or a request to a port (WAKE); `ResumeSandbox` |
| RUNNING or PAUSED | STOPPED | Its 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) |
| STOPPED | RUNNING | `ResumeSandbox`; a call, SSH login or port request only with `wake_when_stopped`, and never after a CRASH |
| Any | DELETED | `DeleteSandbox`; 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](https://pethost.dev/docs/sandboxes/lifecycle/) 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

| What | Pause | Stop | Fork | Template | Delete |
| --- | --- | --- | --- | --- | --- |
| Memory | Kept | Lost | Copied | Not saved | Gone |
| Running processes | Kept | Ended | Copied, running | Not saved | Gone |
| Files and Docker images | Kept | Kept | Copied | Saved | Gone |
| Agent conversations | Kept | Kept | Copied | Not saved | Gone |

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.

[PreviousPethost Agent Sandboxes docs](https://pethost.dev/docs/sandboxes/) [NextQuickstart: your first sandbox](https://pethost.dev/docs/sandboxes/quickstart/)

## 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](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Templates](https://pethost.dev/templates/)
- [About](https://pethost.dev/about/)
- [Docs](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Terms](https://pethost.dev/terms/)
- [Privacy](https://pethost.dev/privacy/)
- [Refunds](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Databases

- [Postgres](https://pethost.dev/postgres/)
- [Valkey](https://pethost.dev/valkey/)

Agent Sandboxes

- [Sandboxes](https://pethost.dev/sandboxes/)
- [Pricing](https://pethost.dev/sandboxes/#pricing)
- [Docs](https://pethost.dev/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Comparisons

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/blog/coolify-cloud-vs-dokploy-cloud/)
- [Railway vs Render vs Fly.io pricing](https://pethost.dev/blog/railway-vs-render-vs-fly-io-pricing/)
- [Managed Docker Compose hosting](https://pethost.dev/blog/managed-docker-compose-hosting/)

Alternatives

- [Railway alternatives](https://pethost.dev/blog/railway-alternatives/)
- [Heroku alternatives](https://pethost.dev/blog/heroku-alternatives/)
- [Dokploy alternatives](https://pethost.dev/blog/dokploy-alternatives/)
- [Coolify alternatives](https://pethost.dev/blog/coolify-alternatives/)
- [Render alternatives](https://pethost.dev/blog/render-alternatives/)
- [Sliplane alternatives](https://pethost.dev/blog/sliplane-alternatives/)
