What counts as idle
A sandbox is idle while nothing happens in it: no call into it and no open stream, no open link, SSH session or request to one of its ports, no agent turn running, and no command running that was started with keep_awake. A background process alone does not keep it awake: when the sandbox pauses, the process is frozen with it and goes on at the wake. Each server looks at every one of its sandboxes once a second.
The three timers: auto-pause, auto-stop, auto-delete
pause_after_idle_seconds, 300 by default: a running sandbox pauses, its memory and processes kept, at 30% of its running price.stop_after_idle_seconds, 1800 by default: a running or paused sandbox stops; its processes end, and its disk goes to object storage at $0.03 per GiB a month of its own data.delete_after_idle_seconds, 0 by default, which is never: a sandbox in any state is deleted.
All three run on one clock, the time since something last happened in the sandbox. A stop timer no later than the pause timer stops a running sandbox without pausing it first. get_sandbox says what the lifecycle does next and when, in next_state and next_state_time. You set the timers when you create a sandbox, change them later with update_sandbox, and a template can carry them for every sandbox made from it.
from pethost.sandboxes import Lifecycle, Sandboxes, SandboxSettings
sandboxes = Sandboxes() # reads PETHOST_TOKEN
lifecycle = Lifecycle(
pause_after_idle_seconds=60, # paused after an idle minute
stop_after_idle_seconds=3600, # stopped after an idle hour
delete_after_idle_seconds=7 * 86400, # deleted after an idle week
)
sandbox = sandboxes.create_sandbox("base", settings=SandboxSettings(lifecycle=lifecycle))
# Work nobody calls into while it runs: keep_awake holds the pause off, for an hour at most.
install = "python3 -m venv env && env/bin/pip install pandas scikit-learn"
sandboxes.run_command(sandbox.sandbox_id, command=install, keep_awake=True, timeout_seconds=3600, wait_seconds=0)id=$(pethost sandbox new --pause-after 1m --stop-after 1h --delete-after 168h)
pethost sandbox run "$id" --keep-awake --timeout 1h -d -- 'python3 -m venv env && env/bin/pip install pandas scikit-learn'When a server runs short
A server may pause or stop sandboxes ahead of their timers. When its memory runs short, it pauses running sandboxes that have been idle for a minute or more; when its disk runs short, it stops the paused sandboxes idle the longest. Nothing is lost either way: a paused sandbox wakes as any other does, a stopped one starts again from its disk, and state_message says why it happened.
Waking a stopped sandbox
A call into a stopped sandbox is refused by default (FAILED_PRECONDITION with Stopped), and a request to one of its ports is answered 503, until resume_sandbox starts it. With wake_when_stopped on, a stopped sandbox wakes at a call, an SSH login or a request to a port, as a paused one does: in about 0.2 s, or about 10 s a GiB when its disk has to be fetched back from object storage. Its vCPUs then count against your plan while it is stopped. It suits a sandbox that a webhook calls now and then.
What idle time costs
No sandbox has a maximum lifetime: one kept awake runs until you stop it, and one left alone costs less at each step. Take one SMALL sandbox that an agent works in for 2 hours a day and leaves idle for the other 22, over a 30-day month. Paused while idle, it costs $4.64 of usage: 60 hours at $0.018 and 660 at $0.0054. Left running, it would cost $12.96. Stopped while idle, with 5 GiB of its own data, it costs $1.22, but each start then boots it from its disk, its processes gone. Per-second billing says how each of those seconds is counted.
How it compares
Other vendors cap how long a sandbox lives. As their pages read on 21 November 2026, E2B’s sessions last up to 1 hour on Hobby and 24 hours on Pro, a pause starting the count again; Modal’s sandboxes live 5 minutes by default and 24 hours at most; and Vercel Sandbox’s sessions last 45 minutes on Hobby and 24 hours on Pro. Pethost sets no cap: a sandbox pauses and stops by its timers, and lives until you, or a delete timer you set, remove it.