Agent Sandboxes docs · Concepts
Sandbox lifecycle: auto-pause, auto-stop and idle
A sandbox you leave alone pauses after 5 minutes and stops after 30, and it is never deleted unless you ask. Three timers on one idle clock decide this, and each of them can be changed or turned off. This page says what counts as activity, what each timer does, and which values suit an agent, an app's users, a preview and a batch job.
- Idle means no call, stream, link, SSH session, port request, agent turn or
keep_awakecommand. A background process alone does not count: it pauses with the sandbox and resumes where it was. - Three timers:
pause_after_idle_seconds(300),stop_after_idle_seconds(1,800) anddelete_after_idle_seconds(off). Each is off with 0. - Long work that nobody calls into, such as a build or a test suite, runs with
keep_awake, so the sandbox does not pause under it. - A stopped sandbox starts again by
ResumeSandbox, or at the next call whenwake_when_stoppedis on. next_stateandnext_state_timeon a sandbox say what its lifecycle does next, and when.
What counts as activity
A sandbox is idle while nothing happens in it. Each of these keeps it awake, and resets its idle clock when it ends:
- a call of the runtime API (a command, a file, the desktop, an agent), or one of its streams left open;
- an open link: a terminal or a live view of the desktop in a browser;
- an SSH session;
- a request to one of its ports;
- an agent's turn that is still running;
- a command started with
keep_awake, until it ends.
What does not count is a process running in the background on its own: a dev server, a job started with nohup, a watcher. When the sandbox pauses, such a process stops where it is, and it goes on from there when the sandbox wakes. A server needs nothing more: a request to its port wakes the sandbox.
The default timeline
- 0 minThe last activity: it runs.
- 5 minPAUSED: memory and processes kept on its server, at 30% of the price.
- 30 minSTOPPED: its disk kept, its processes ended, $0.03 a GiB a month.
- NeverDeleted only by you, or by its delete timer.
The three timers
A sandbox's lifecycle has three timers, each a number of seconds on the same idle clock, each off with 0:
| Field | Default | What happens |
|---|---|---|
pause_after_idle_seconds | 300 | A RUNNING sandbox becomes PAUSED. |
stop_after_idle_seconds | 1,800 | A RUNNING or PAUSED sandbox becomes STOPPED. |
delete_after_idle_seconds | 0, never | A sandbox in any state is deleted. |
When the stop timer comes no later than the pause timer, an idle RUNNING sandbox stops without pausing. With both off, a sandbox runs until you pause, stop or delete it.
Set the lifecycle when you create a sandbox, or later with UpdateSandbox. The lifecycle is one group of settings: a group you send replaces the sandbox's whole group, and a timer you leave out takes its default. So send every timer you mean to set. Each answer carries the settings in force with their defaults filled in, so what you read is what you send back.
from pethost.sandboxes import Lifecycle, SandboxSettings, Sandboxes
sandboxes = Sandboxes() # The token: PETHOST_TOKEN.
sandbox = sandboxes.create_sandbox(
settings=SandboxSettings(
lifecycle=Lifecycle(
pause_after_idle_seconds=300, # pause after 5 idle minutes
stop_after_idle_seconds=86400, # stop after an idle day
),
),
)
print(sandbox.sandbox_id)
import { Sandboxes } from "pethost/sandboxes";
const sandboxes = new Sandboxes({ token: process.env.PETHOST_TOKEN! });
const sandbox = await sandboxes.createSandbox({
settings: {
lifecycle: { pauseAfterIdleSeconds: 300, stopAfterIdleSeconds: 86400 },
},
});
console.log(sandbox.sandboxId);
client := sandboxes.NewClient(sandboxes.Config{Token: os.Getenv("PETHOST_TOKEN")})
sandbox, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{
Settings: &sandboxes.SandboxSettings{
Lifecycle: &sandboxes.Lifecycle{
PauseAfterIdleSeconds: new(uint32(300)),
StopAfterIdleSeconds: new(uint32(86400)),
},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(sandbox.SandboxID)
use pethost::sandboxes::{types::*, Client};
let sandboxes = Client::new(&std::env::var("PETHOST_TOKEN")?);
let sandbox = sandboxes
.create_sandbox(CreateSandboxRequest {
settings: Some(SandboxSettings {
lifecycle: Some(Lifecycle {
pause_after_idle_seconds: Some(300),
stop_after_idle_seconds: Some(86400),
..Default::default()
}),
..Default::default()
}),
..Default::default()
})
.await?;
println!("{}", sandbox.sandbox_id);
pethost sandbox new --pause-after 5m --stop-after 24h
CreateSandbox {"settings": {"lifecycle": {"pause_after_idle_seconds": 300, "stop_after_idle_seconds": 86400}}}
curl https://console.pethost.dev/pethost.sandboxes.v1.SandboxService/CreateSandbox \
-H "Authorization: Bearer $PETHOST_TOKEN" \
-H "Content-Type: application/json" \
-d '{"settings": {"lifecycle": {"pause_after_idle_seconds": 300, "stop_after_idle_seconds": 86400}}}'
Long work: keep_awake
A build, a test suite or a training run may take minutes with no call into the sandbox, and the pause timer would pause it under the work. Start such a command with keep_awake: while it runs, the sandbox does not pause for idleness, and it counts as RUNNING. Give it timeout_seconds too, so that a command that hangs does not keep the sandbox awake for good.
command = sandboxes.run_command(
sandbox.sandbox_id,
command="npm ci && npm test",
keep_awake=True,
timeout_seconds=1800,
wait_seconds=0, # answer once it has started
)
print(command.command_id, command.state.name)
const command = await sandboxes.runCommand({
sandboxId: sandbox.sandboxId,
command: "npm ci && npm test",
keepAwake: true,
timeoutSeconds: 1800,
waitSeconds: 0, // answer once it has started
});
console.log(command.commandId, command.state);
command, err := client.RunCommand(ctx, &sandboxes.RunCommandRequest{
SandboxID: sandbox.SandboxID,
Command: "npm ci && npm test",
KeepAwake: true,
TimeoutSeconds: 1800,
WaitSeconds: new(uint32(0)), // answer once it has started
})
let command = sandboxes
.run_command(RunCommandRequest {
sandbox_id: sandbox.sandbox_id.clone(),
command: "npm ci && npm test".into(),
keep_awake: true,
timeout_seconds: 1800,
wait_seconds: Some(0), // answer once it has started
..Default::default()
})
.await?;
pethost sandbox run k7f3q2xy0a1b2c3d -d --keep-awake --timeout 30m -- 'npm ci && npm test'
There is no cap on a sandbox's life: one kept awake runs, and is billed, until its command ends or you stop it.
Waking a stopped sandbox: wake_when_stopped
By default a STOPPED sandbox wakes only by ResumeSandbox. A runtime call into it answers FAILED_PRECONDITION with Stopped, and a request to one of its ports answers HTTP 503, “stopped: resume it”.
With wake_when_stopped on, a stopped sandbox wakes at a call, an SSH login or a port request, as a paused one does: about 0.2 s while its disk is on its server, longer when the disk comes back from object storage, about 10 s a GiB of its own data. It suits a project that wakes now and then, such as a webhook's endpoint or a sandbox your app calls without resuming it first.
It has a cost in budget, not in money: such a sandbox's vCPUs count against your plan while it is stopped too, so that it always has room to wake. Turning it on for a stopped sandbox is refused when the workspace has no vCPUs left, and turning it off frees them. A sandbox stopped by a CRASH never wakes this way.
Cleaning up by itself: delete_after_idle_seconds
A stopped sandbox costs only its stored bytes, but it costs them every month. For sandboxes you will not come back to, set delete_after_idle_seconds: once idle that long, in any state, the sandbox is deleted, with its memory and disk. Its volumes stay. Its record stays 30 days, and its events and metrics a day. Your program can also call DeleteSandbox when it is done, which is the surest way.
When a sandbox pauses or stops early
A sandbox may pause or stop before its timers say, when its server runs short of room:
- Memory short: a RUNNING sandbox idle for 1 minute or more is paused early. Its
state_messagesays “paused early: its server's memory ran short”. - Disk short: the server stops the PAUSED sandboxes idle the longest, “stopped early: its server's disk ran short”, and a pause becomes a stop meanwhile, “stopped instead of paused”.
- Disk out: the server stops the RUNNING sandbox whose disk grew most, with the reason CRASH, “its server ran out of disk space”. Its disk is kept.
A sandbox that is not idle is never paused early for memory.
What happens next: next_state and the reasons
GetSandbox answers with next_state and next_state_time: what the lifecycle does to the sandbox next if nothing happens before, PAUSED, STOPPED or DELETED, and when. They are absent while something keeps the sandbox awake, and when no timer runs in its state.
Every change of state has a state_reason, and the sandbox's events show the same reasons:
| Reason | What it means |
|---|---|
REQUEST | A call asked for it. |
IDLE | A timer, or its server short of memory or disk. |
WAKE | A call, an SSH login or a port request resumed it. |
CRASH | Its VM or its server failed, or it did not start. Only ResumeSandbox starts it again. |
MAINTENANCE | Its server's machine restarted: paused before, not billed, and running again after. |
UNPAID | Nothing pays for the workspace: billing. |
Values per use case
These are recommendations, built from the rules above. The timers are in seconds, as the API takes them.
| Use case | Pause | Stop | Delete | wake_when_stopped | keep_awake |
|---|---|---|---|---|---|
| An agent's session, such as Claude Code in the cloud | 300, the default | 0, or 86400 | 0 | No | On long builds |
| A sandbox per user of your AI app | 60 to 300 | 1800, the default | 604800 | If your app calls without ResumeSandbox | No |
| A preview that sleeps | 120 | 0 | 2592000 | No | No |
| A batch job or an eval | 0 | 60 | 600, or DeleteSandbox at the end | No | On the job's command |
An agent's sandbox keeps its processes when it never stops, and a paused day costs 30% of a running one. A preview with no stop timer wakes at a visit in about 0.2 s with its dev server where it was. Billing works out what each costs.
When it does not work
- It paused during a long build. Nothing called into it, and a build is a background process. Run the build with
keep_awake. - A call answers FAILED_PRECONDITION with Stopped. The sandbox is STOPPED. Call
ResumeSandbox, or turn onwake_when_stopped. - A port answers 503, “stopped: resume it”. The same, seen from a browser or curl.
- A call answers UNAVAILABLE with Restoring. Its disk is coming back from object storage, about 10 s a GiB. Wait, or call
ResumeSandboxagain to follow it. - It paused before its timer. Its server ran short of memory:
state_messagesays so. It wakes as usual at the next call.
Questions
Does a background process keep a sandbox awake?
No. Only calls, open streams and links, SSH sessions, port requests, running agent turns and commands started with keep_awake do. A background process pauses with the sandbox and goes on when it wakes.
How do I keep a sandbox from ever stopping?
Set stop_after_idle_seconds to 0. It still pauses when idle, which keeps its processes, and wakes at the next call.
How do I keep a sandbox running all the time?
Set both pause_after_idle_seconds and stop_after_idle_seconds to 0, and it runs until you pause, stop or delete it, at its running price.
Does a stopped sandbox wake when I call it?
Only with wake_when_stopped on, whose vCPUs then count against your plan while it is stopped. Otherwise ResumeSandbox starts it.
Are idle sandboxes deleted automatically?
Not by default. Set delete_after_idle_seconds, or call DeleteSandbox when you are done.
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.