---
title: "Sandbox lifecycle: auto-pause, auto-stop and idle | Pethost Agent Sandboxes"
description: "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."
---

[Agent Sandboxes docs](https://pethost.dev/docs/sandboxes/) · Concepts

# Sandbox lifecycle: auto-pause, auto-stop and idle

Updated 22 November 2026 · 8 min read

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.

**In short**

- **Idle** means no call, stream, link, SSH session, port request, agent turn or `keep_awake` command. 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) and `delete_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 when `wake_when_stopped` is on.
- `next_state` and `next_state_time` on 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

1. **0 min**The last activity: it runs.
2. **5 min**PAUSED: memory and processes kept on its server, at 30% of the price.
3. **30 min**STOPPED: its disk kept, its processes ended, $0.03 a GiB a month.
4. **Never**Deleted only by you, or by its delete timer.

The idle clock starts again at each activity: a call at minute 4 puts the pause off until minute 9.

## 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.

Python

```
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)
```

TypeScript

```
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);
```

Go

```
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)
```

Rust

```
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);
```

CLI

```
pethost sandbox new --pause-after 5m --stop-after 24h
```

MCP

```
CreateSandbox {"settings": {"lifecycle": {"pause_after_idle_seconds": 300, "stop_after_idle_seconds": 86400}}}
```

HTTP

```
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.

Python

```
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)
```

TypeScript

```
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);
```

Go

```
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
})
```

Rust

```
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?;
```

CLI

```
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_message` says “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](https://pethost.dev/docs/sandboxes/billing/#unpaid). |

## 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](https://pethost.dev/docs/sandboxes/billing/#examples) 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 on `wake_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 `ResumeSandbox` again to follow it.
- **It paused before its timer.** Its server ran short of memory: `state_message` says 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.

[PreviousConnect an agent to sandboxes over MCP](https://pethost.dev/docs/sandboxes/connect-an-agent/) [NextSandbox pricing and billing: per second, by state](https://pethost.dev/docs/sandboxes/billing/)

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