---
title: "Pethost Agent Sandboxes docs"
description: "How Pethost Agent Sandboxes work and what they cost: Firecracker microVMs for code, coding agents and a browser, from your code or your agent."
---

# Pethost Agent Sandboxes docs

Updated 22 November 2026 · 2 min read

A sandbox is a Linux microVM for code, coding agents and a desktop with Chrome: a Firecracker VM with its own kernel, and root inside. It starts from a template in about 0.15 s, pauses with its memory and processes when nothing happens in it, wakes at the next call in about 0.1 s, and stops to object storage when it stays idle longer. You pay by the second for what each state holds.

**RUNNING**

In its server's memory

Runs your processes and answers every call.

$0.018 an hour, SMALL

Idle 5 min: it pauses

The next call wakes it

**PAUSED**

On its server's disk

Keeps memory, processes and disk.

$0.0054 an hour, SMALL

Idle 30 min: it stops

**STOPPED**

In object storage

Keeps its disk; its processes end.

$0.03 a GiB a month

ResumeSandbox starts it again, its files as it left them

The default lifecycle. Each timer can be changed or turned off, and a sandbox is never deleted unless you ask: [lifecycle and idle](https://pethost.dev/docs/sandboxes/lifecycle/).

## Where to start

[**Write code** The quickstart: a sandbox, a command, a file and a public URL from Python, TypeScript, Go or Rust, or from the pethost CLI.](https://pethost.dev/docs/sandboxes/quickstart/) [**Give it to your agent** Add the MCP server to Claude, Codex, Cursor or another MCP client, and the agent makes and uses sandboxes itself.](https://pethost.dev/docs/sandboxes/connect-an-agent/) [**Understand it first** The three states, what wakes a sandbox, and where each byte of it lives.](https://pethost.dev/docs/sandboxes/how-it-works/)

## In numbers

- **0.15 s** to start a sandbox, measured through a panel 16 ms from its server
- **0.1 s** to wake a paused one, at its next call
- **$0.018** an hour for 2 vCPUs and 4 GiB, by the second
- **30%** of that price while it is paused

## What a sandbox does

- **Commands, files and a terminal.** Run a command and wait for its port, edit a file by exact replacement, stream output, or open a terminal in a browser: [commands and files](https://pethost.dev/docs/sandboxes/commands-and-files/).
- **Ports.** Any port at `https://<port>-<id>.<server>`, public or behind a token: [ports and previews](https://pethost.dev/docs/sandboxes/ports-and-previews/).
- **Coding agents.** Claude Code, Codex and OpenCode are installed. One call gives an agent a prompt, another streams each tool call it makes: [coding agents](https://pethost.dev/docs/sandboxes/coding-agents/).
- **A desktop.** Chrome on a 1280×800 screen, which starts at its first use: click, type and take a screenshot in one call, or watch it live: [computer use](https://pethost.dev/docs/sandboxes/computer-use/).
- **Templates, forks and volumes.** Save a sandbox's disk and start new ones from it ([templates](https://pethost.dev/docs/sandboxes/templates/)); copy a running sandbox, memory and all, into up to 100 copies ([forks](https://pethost.dev/docs/sandboxes/forks/)); keep data on a disk outside any sandbox, on one server ([volumes](https://pethost.dev/docs/sandboxes/volumes/)).
- **Secrets and egress.** API keys the sandbox never holds, and an allow-list of where it may connect: [secrets and egress](https://pethost.dev/docs/sandboxes/secrets-and-egress/).
- **SSH and observability.** Plain `ssh`, `scp` and `ssh -L` ([SSH](https://pethost.dev/docs/sandboxes/ssh/)), and each sandbox's metrics, events and usage ([observability](https://pethost.dev/docs/sandboxes/observability/)).

## Agent Sandboxes and App Platform

Pethost has two kinds of workspace. **App Platform** is a plan's machine for your Docker Compose apps, at a flat price a month: its docs are the [App Platform docs](https://pethost.dev/docs/). **Agent Sandboxes** is what these pages are about: microVMs that your code or your agent starts, uses and stops through an API, billed by the second. Each workspace is of one kind, and one account can have both.

## Every page

### Start

- [How Pethost Agent Sandboxes work](https://pethost.dev/docs/sandboxes/how-it-works/) 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.
- [Quickstart: your first sandbox](https://pethost.dev/docs/sandboxes/quickstart/) Create a sandbox, run a command, write a file, open a port and clean up: from Python, TypeScript, Go, Rust, the pethost CLI or your agent.
- [Connect an agent to sandboxes over MCP](https://pethost.dev/docs/sandboxes/connect-an-agent/) Give Claude Code, Codex, Cursor or Claude sandboxes as tools: add the Pethost Agent Sandboxes MCP server and sign in to a workspace of sandboxes.

### Concepts

- [Sandbox lifecycle: auto-pause, auto-stop and idle](https://pethost.dev/docs/sandboxes/lifecycle/) When an idle sandbox pauses, stops or is deleted: what counts as activity, the three timers, keep_awake, wake_when_stopped, and values per use case.
- [Sandbox pricing and billing: per second, by state](https://pethost.dev/docs/sandboxes/billing/) What a sandbox costs each second it runs, pauses or sleeps, what a plan includes, free starts and their limits, the trial, and worked examples.
- [Best practices for Pethost Agent Sandboxes](https://pethost.dev/docs/sandboxes/best-practices/) The few choices that make sandboxes start fast, cost less and stay safe: templates, pausing for agents, batch jobs, keep_awake, request_id, secrets, egress.

### Tasks

- [Run commands and edit files in a sandbox](https://pethost.dev/docs/sandboxes/commands-and-files/) Run shell commands in a sandbox and wait for their output or port, stream long ones, edit files by exact replacement, and move large files through links.
- [Ports and previews: a sandbox's URLs](https://pethost.dev/docs/sandboxes/ports-and-previews/) Give any port of a sandbox an HTTPS address, public or behind a token, wait for a dev server to listen, and run previews that sleep between visits.
- [Run Claude Code, Codex and OpenCode in a sandbox](https://pethost.dev/docs/sandboxes/coding-agents/) Give Claude Code, Codex or OpenCode a prompt in a sandbox with one call, stream its tool calls, and sign it in without the key entering the sandbox.
- [Computer use: Chrome on a desktop in a sandbox](https://pethost.dev/docs/sandboxes/computer-use/) Click, type and take a screenshot of a desktop with Chrome in one call, for a computer-use agent, or watch the sandbox's screen live in a browser.
- [Templates: start sandboxes ready to work](https://pethost.dev/docs/sandboxes/templates/) Save a sandbox's disk as a template, with your packages and Docker images, and start new sandboxes from it on any server in about 0.2 s.
- [Secrets and egress: keys a sandbox never holds](https://pethost.dev/docs/sandboxes/secrets-and-egress/) Give a sandbox API keys it never holds, swapped in by the egress proxy for the hosts you name, and limit where it may connect with an allow-list.
- [Fork a sandbox, memory and processes included](https://pethost.dev/docs/sandboxes/forks/) Copy a running sandbox, with its memory, processes and disk, into up to 100 sandboxes in one call, to try several things from the same point at once.
- [Volumes: a disk that outlives sandboxes](https://pethost.dev/docs/sandboxes/volumes/) Create a volume, mount it into sandboxes at a path, read-write by one or read-only by many, and know where it lives and what it costs.
- [SSH into a sandbox: shell, scp, SFTP and tunnels](https://pethost.dev/docs/sandboxes/ssh/) Sign in to any sandbox with plain ssh, copy files with scp and SFTP, and forward its ports with ssh -L, with a workspace key or a token as the password.
- [Observability: a sandbox's metrics, events and usage](https://pethost.dev/docs/sandboxes/observability/) Read a sandbox's CPU, memory, disk and network, list and stream its lifecycle, commands, connections, port requests and agent turns, and see what it cost.

### Reference

- [Limits of Pethost Agent Sandboxes](https://pethost.dev/docs/sandboxes/limits/) Every bound of Pethost Agent Sandboxes in one place: sizes, plan budgets, start limits, per-sandbox and per-call limits, kept history and the network.
- [Errors of the sandboxes API, and what to do](https://pethost.dev/docs/sandboxes/errors/) Every refusal of the sandboxes API, its code and typed detail, what it means and what your program or agent should do next.

[NextHow Pethost Agent Sandboxes work](https://pethost.dev/docs/sandboxes/how-it-works/)

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