English
Docs menu

Agent Sandboxes docs · Concepts

Best practices for Pethost Agent Sandboxes

Updated · 8 min read

A handful of choices decide how fast your sandboxes start, what they cost while they wait, and what an agent inside one can reach. Each practice below is a rule, the number behind it, and the fields that do it. Most of them are a setting you make once.

In short
  • Speed: save your setup as a template, start servers with wait_for_port, and fork for parallel attempts.
  • Cost: let an agent's sandbox pause instead of stop, delete batch sandboxes when they are done, and start small.
  • Reliability: mark long commands keep_awake, retry with request_id, stream instead of polling, and keep volumes for what must outlive a sandbox.
  • Security: bind API keys as secrets, narrow egress for code you did not write, and treat everything a sandbox returns as data.
  • Order: label every sandbox, and list them by label.

Speed

Save your setup as a template

Installing your dependencies at every start costs the same minutes every time. Install them once in a sandbox, then save its disk with CreateTemplate: packages, build caches and Docker images included. A sandbox from your template starts in about 0.22 s with everything in place, on any server: the first on each server fetches the version, about 10 s a GiB, and the next ones start from its copy. Keep secrets out of the files you save, since every sandbox made from the template gets them, and make a new version when your dependencies change: my-app starts from the newest, my-app@3 from that one.

Start servers with wait_for_port

A dev server takes a moment to listen, and polling it from outside wastes calls. Run it with wait_for_port: RunCommand answers as soon as something listens on that port, while the command runs on, so one call starts the server and tells you it is up. Then open the port publicly, or give your page a token for it: ports and previews.

Fork for parallel attempts

When an agent should try several fixes, or an eval should start many runs from one prepared state, fork the sandbox instead of rebuilding that state. ForkSandbox copies memory, processes and disk into up to 100 new sandboxes in one call: a copy took about 0.25 s. Each copy is a start, and all are made or none. Two things to know:

  • Reseed random generators in the copies. Each copy has its own kernel randomness, but the random generators already running in its processes (OpenSSL's, Python's, Node's, Go's) give the same numbers in every copy until reseeded.
  • A read-write volume refuses a fork, since only one sandbox may write it. A volume mounts at create only, so mount it with read_only in a sandbox you mean to fork.

Cost

Let an agent's sandbox pause, not stop

An agent's sandbox waits most of the time, and stopping it ends its processes: the dev server, the REPL, the browser it had open. Keep the pause timer, and raise the stop timer or turn it off (stop_after_idle_seconds 0). Paused, the sandbox costs 30% of its running price and wakes at the next call in about 0.1 s, with everything where it was. A DEFAULT sandbox at work 2 hours a day and paused the rest costs about $9.42 a month, against $26.28 always running.

An agent's sessionPauses between turns, never stops

  1. running
  2. paused
  3. running
  4. paused

A user's sandbox in your appPauses, then stops after half an hour

  1. running
  2. paused
  3. stopped

A preview that sleepsWakes at each visit

  1. paused
  2. running
  3. paused
  4. running
  5. paused

A batch jobRuns, then is deleted

  1. running
  2. stopped
  3. deleted
  • RUNNING
  • PAUSED
  • STOPPED
  • DELETED
Four jobs over a day, each with its own lifecycle. The values are in lifecycle and idle.

Delete batch sandboxes when they are done

A sandbox for one job, a test run or an eval case, should cost nothing once the job ends. Call DeleteSandbox at the end, and set delete_after_idle_seconds as a net for a job that dies before it gets there. Turn the pause timer off and give it a short stop timer, so that an idle job's sandbox goes quickly. A stopped sandbox you forget costs $0.03 a GiB a month, every month. Starts are free, so a fresh sandbox per job costs only its seconds: 1,000 runs of 40 s on SMALL cost $0.20.

Start small, and resize when you need to

A size is its vCPUs, memory and disk, and its price doubles with each size up. Start with SMALL, $0.018 an hour, and watch GetSandboxMetrics. When a job needs more, UpdateSandbox with a new size restarts a RUNNING sandbox in a VM of that size, its files kept, in about 283 ms: its processes end, so resize between jobs. Add grow_disk to grow the disk to the new size's; a disk never shrinks, so a grown sandbox cannot go back to a smaller size.

Reliability

Mark long commands keep_awake

A build or a test suite can run for minutes with no call into the sandbox, and the pause timer would pause it under the work. Start it with keep_awake, and with timeout_seconds, so that a command that hangs does not keep the sandbox running for good. A server needs neither: a request to its port wakes the sandbox. Lifecycle and idle has the details.

Retry with request_id

A network can drop the answer of a call that did its work. A call that makes something takes a request_id: a retry with the same id within 24 hours answers what the first call did and does nothing again. CreateSandbox, ForkSandbox, CreateTemplate, CreateVolume, RunCommand and PromptAgent take one. Make it once per thing you mean to do, keep it, and send it again on each retry. One caveat: a sandbox keeps the ids of what runs in it on its disk, so one that stopped may have lost those of its last seconds, and a retry of such a command runs it again.

Python
import uuid

from pethost.sandboxes import Label, Sandboxes

sandboxes = Sandboxes()  # The token: PETHOST_TOKEN.
request_id = str(uuid.uuid4())  # Keep it: a retry sends the same one.

sandbox = sandboxes.create_sandbox(
    template="my-app",
    labels=[Label(key="user", value="42"), Label(key="job", value="nightly-evals")],
    request_id=request_id,
)
TypeScript
import { Sandboxes } from "pethost/sandboxes";

const sandboxes = new Sandboxes({ token: process.env.PETHOST_TOKEN! });
const requestId = crypto.randomUUID(); // Keep it: a retry sends the same one.

const sandbox = await sandboxes.createSandbox({
  template: "my-app",
  labels: [{ key: "user", value: "42" }, { key: "job", value: "nightly-evals" }],
  requestId,
});
Go
requestID := rand.Text() // crypto/rand. Keep it: a retry sends the same one.

sandbox, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{
	Template:  "my-app",
	Labels:    []sandboxes.Label{{Key: "user", Value: "42"}, {Key: "job", Value: "nightly-evals"}},
	RequestID: requestID,
})
Rust
let request_id = uuid::Uuid::new_v4().to_string(); // Keep it: a retry sends the same one.

let sandbox = sandboxes
    .create_sandbox(CreateSandboxRequest {
        template: "my-app".into(),
        labels: vec![
            Label { key: "user".into(), value: "42".into() },
            Label { key: "job".into(), value: "nightly-evals".into() },
        ],
        request_id: request_id.clone(),
        ..Default::default()
    })
    .await?;
MCP
CreateSandbox {"template": "my-app", "labels": [{"key": "user", "value": "42"}], "request_id": "b7e1c2d4-0f3a-4c55-9a7e-2d1f6c8e9a10"}
HTTP
curl https://console.pethost.dev/pethost.sandboxes.v1.SandboxService/CreateSandbox \
  -H "Authorization: Bearer $PETHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "my-app", "labels": [{"key": "user", "value": "42"}], "request_id": "b7e1c2d4-0f3a-4c55-9a7e-2d1f6c8e9a10"}'

Stream instead of polling

Polling a command or a sandbox costs a call each time and still learns late. A call that waits does the waiting for you: RunCommand, GetCommand, PromptAgent and GetAgentTurn wait up to 45 s (wait_seconds) and answer as soon as the work ends. To follow work as it happens, stream it: WatchCommand for a command's output, WatchConversation for an agent's messages and tool calls, WatchSandboxEvents for a sandbox's lifecycle, commands and connections.

Use volumes only for what must outlive a sandbox

A volume is a disk outside every sandbox, mounted at a path: datasets, caches shared by many sandboxes, a database's files. It lives on one server's disk and is not copied anywhere, so if that server is lost, so is the volume. A sandbox that mounts one cannot move to another server, and a read-write mount refuses forks. Most work needs no volume: a sandbox's own disk survives pauses and stops, and a template carries files to new sandboxes. What must not be lost, push to a store of your own as well.

Security

Bind API keys as secrets

A key in a plain environment variable is readable by every process in the sandbox, and by an agent that prints its environment. Save it as a workspace secret instead, with the hosts it is for (SetSecret: anthropic, api.anthropic.com), and bind a variable to it (ANTHROPIC_API_KEY, secret anthropic). The variable then holds a placeholder, phs_…, and the egress proxy puts the real key into the headers of HTTPS requests to those hosts only. A new value works at once in every sandbox that binds it: secrets and egress.

Narrow egress for code you did not write

By default a sandbox may connect anywhere. For untrusted code, list where it may go (egress.allow): a domain such as pypi.org, its subdomains with *.github.com (which leaves out github.com itself), an IP or a CIDR, each with a port where it is not 80 and 443, as github.com:22 for git over SSH. deny wins over allow. The sandbox's DNS answers only names the list allows, and only TCP and DNS leave a sandbox: no UDP, and no ping. A change applies at once and closes connections it no longer allows.

Treat what a sandbox returns as data

Command output, file contents, an agent's messages, screenshots and the pages a browser loads come from programs and the internet. When a model reads them, they are data, never instructions: a README or a web page can hold text written to steer an agent. Keep that line in your prompts, and give a sandbox that runs untrusted work no more secrets and no wider egress than the work needs.

Order

Label every sandbox

A label is a key and a value of yours: user=42, job=nightly-evals, run=7f3a. A sandbox takes up to 32, and ListSandboxes lists the sandboxes that have all the labels you name. So your app finds a user's sandboxes without a table of its own, a cleanup job finds a run's leftovers, and the console shows whose each sandbox is. A label is for finding many; a name is for calling one: unique in the workspace, up to 63 characters of a-z, 0-9 and "-", and ListSandboxes with name finds its id.

Questions

Should I stop or pause an idle sandbox?

Pause it when its processes matter or it will be used again soon: it wakes in about 0.1 s where it was, at 30% of the running price. Stop it for a long sleep: then it costs only its stored data.

How do I make sandboxes start faster?

Save your setup as a template, so nothing is installed at start: a sandbox from it starts in about 0.22 s with your packages and Docker images.

How do I keep API keys out of a sandbox?

Save each key as a workspace secret with its hosts, and bind an environment variable to it. The sandbox sees a placeholder, and the egress proxy adds the real key to requests to those hosts.

How many sandboxes can I run at once?

As many as your plan's vCPUs hold, running or paused: 10 SMALL on the $20 plan, 64 on the $100 plan. Stopped sandboxes do not count.

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