English
Get started

Agent Sandboxes Pauses itself when idle

Idle sandboxes pause and stop by themselves

You do not write the code that cleans up after an agent. Three timers on each sandbox decide what an idle one becomes: paused after 5 minutes, stopped after 30, never deleted. Each is set per sandbox, and 0 turns it off.

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.

Read the docs

Questions

Will a long build be paused halfway?

Not when you start it with keep_awake: the sandbox does not pause for idleness while that command runs. Give it timeout_seconds too, so that a command that hangs does not keep it awake for good.

Can a sandbox never pause?

Yes: set pause_after_idle_seconds to 0. It then runs, billed as running, until its stop timer or you stop it.

What wakes a stopped sandbox?

resume_sandbox, or, with wake_when_stopped on, any call into it, SSH login or request to one of its ports.

Do auto-pause and auto-stop delete anything?

No. A pause keeps memory, processes and disk, a stop keeps the disk, and nothing is deleted unless you set delete_after_idle_seconds.

Is there a maximum lifetime?

No. A sandbox lives until you delete it, or until a delete timer you set does.

Related

Give your agent a computer in 0.15 s

Start the free trial