---
title: "Ciclo de vida do sandbox: pausa automática, parada automática e ociosidade | Pethost Agent Sandboxes"
description: "Quando um sandbox ocioso pausa, para ou é excluído: o que conta como atividade, os três timers, keep_awake, wake_when_stopped e valores por caso de uso."
---

[Docs do Agent Sandboxes](https://pethost.dev/pt/docs/sandboxes/) · Conceitos

# Ciclo de vida do sandbox: pausa automática, parada automática e ociosidade

Atualizado em 22 de novembro de 2026 · 8 min de leitura

Um sandbox que você deixa de lado pausa depois de 5 minutos e para depois de 30, e nunca é excluído a não ser que você peça. Três timers em um mesmo relógio de ociosidade decidem isso, e cada um pode ser alterado ou desativado. Esta página diz o que conta como atividade, o que cada timer faz e quais valores servem para um agente, para os usuários de um app, para um preview e para um job em lote.

**Em resumo**

- **Ocioso** quer dizer sem chamada, stream, link, sessão SSH, requisição a uma porta, turno de agente ou comando `keep_awake`. Um processo em segundo plano sozinho não conta: ele pausa com o sandbox e continua de onde estava.
- **Três timers:** `pause_after_idle_seconds` (300), `stop_after_idle_seconds` (1.800) e `delete_after_idle_seconds` (desativado). Cada um é desativado com 0.
- **Trabalho longo** que ninguém chama, como um build ou uma suíte de testes, roda com `keep_awake`, para o sandbox não pausar no meio dele.
- **Um sandbox parado** inicia de novo por `ResumeSandbox`, ou na próxima chamada quando `wake_when_stopped` está ativado.
- `next_state` e `next_state_time` em um sandbox dizem o que o ciclo de vida faz a seguir, e quando.

## O que conta como atividade

Um sandbox fica ocioso enquanto nada acontece nele. Cada um destes o mantém acordado e zera o relógio de ociosidade quando termina:

- uma chamada da API de runtime (um comando, um arquivo, o desktop, um agente), ou um dos streams dela deixado aberto;
- um link aberto: um terminal ou uma visão ao vivo do desktop em um navegador;
- uma sessão SSH;
- uma requisição a uma das portas dele;
- um turno de agente ainda rodando;
- um comando iniciado com `keep_awake`, até ele terminar.

O que não conta é um processo rodando sozinho em segundo plano: um servidor de desenvolvimento, um job iniciado com `nohup`, um watcher. Quando o sandbox pausa, esse processo para onde está e continua dali quando o sandbox acorda. Um servidor não precisa de mais nada: uma requisição à porta dele acorda o sandbox.

## A linha do tempo padrão

1. **0min**A última atividade: ele roda.
2. **5min**PAUSED: memória e processos guardados no servidor, por 30% do preço.
3. **30min**STOPPED: disco guardado, processos encerrados, US$ 0,03 por GiB ao mês.
4. **Nunca**Excluído só por você, ou pelo timer de exclusão.

O relógio de ociosidade recomeça a cada atividade: uma chamada no minuto 4 adia a pausa para o minuto 9.

## Os três timers

O `lifecycle` de um sandbox tem três timers, cada um em segundos no mesmo relógio de ociosidade, cada um desativado com 0:

| Campo | Padrão | O que acontece |
| --- | --- | --- |
| `pause_after_idle_seconds` | 300 | Um sandbox RUNNING vira PAUSED. |
| `stop_after_idle_seconds` | 1.800 | Um sandbox RUNNING ou PAUSED vira STOPPED. |
| `delete_after_idle_seconds` | 0, nunca | Um sandbox em qualquer estado é excluído. |

Quando o timer de parada vence antes ou junto com o de pausa, um sandbox RUNNING ocioso para sem pausar. Com os dois desativados, um sandbox roda até você pausá-lo, pará-lo ou excluí-lo.

Defina o ciclo de vida ao criar um sandbox, ou depois com `UpdateSandbox`. O ciclo de vida é um grupo de configurações: um grupo que você envia substitui o grupo inteiro do sandbox, e um timer que você deixa de fora volta ao padrão. Então envie todos os timers que pretende definir. Cada resposta traz as configurações em vigor com os padrões preenchidos, e o que você lê é o que você envia de volta.

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

## Trabalho longo: keep_awake

Um build, uma suíte de testes ou um treinamento pode levar minutos sem nenhuma chamada ao sandbox, e o timer de pausa o pausaria no meio do trabalho. Inicie um comando assim com `keep_awake`: enquanto ele roda, o sandbox não pausa por ociosidade e conta como RUNNING. Dê também um `timeout_seconds`, para que um comando travado não mantenha o sandbox acordado para sempre.

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

Não há limite para a vida de um sandbox: um que fica acordado roda, e é cobrado, até o comando terminar ou você pará-lo.

## Acordar um sandbox parado: wake_when_stopped

Por padrão, um sandbox STOPPED só acorda por `ResumeSandbox`. Uma chamada de runtime a ele responde `FAILED_PRECONDITION` com `Stopped`, e uma requisição a uma das portas dele responde HTTP 503, “stopped: resume it”.

Com `wake_when_stopped` ativado, um sandbox parado acorda com uma chamada, um login SSH ou uma requisição a uma porta, como um pausado: cerca de 0,2 s enquanto o disco está no servidor, mais quando o disco volta do armazenamento de objetos, cerca de 10 s por GiB dos próprios dados. Serve para um projeto que acorda de vez em quando, como o endpoint de um webhook ou um sandbox que o seu app chama sem retomá-lo antes.

O custo é no orçamento, não em dinheiro: as vCPUs de um sandbox assim contam no seu plano também enquanto ele está parado, para que sempre haja espaço para ele acordar. Ativar isso em um sandbox parado é recusado quando o espaço de trabalho não tem mais vCPUs, e desativar as libera. Um sandbox parado por um CRASH nunca acorda assim.

## Limpeza automática: delete_after_idle_seconds

Um sandbox parado custa só os bytes guardados, mas custa todo mês. Para sandboxes a que você não vai voltar, defina `delete_after_idle_seconds`: depois de ocioso por esse tempo, em qualquer estado, o sandbox é excluído, com memória e disco. Os volumes dele ficam. O registro fica 30 dias, e os eventos e as métricas, um dia. O seu programa também pode chamar `DeleteSandbox` quando terminar, que é o jeito mais seguro.

## Quando um sandbox pausa ou para antes da hora

Um sandbox pode pausar ou parar antes do que os timers dizem, quando o servidor dele fica sem espaço:

- **Pouca memória:** um sandbox RUNNING ocioso há 1 minuto ou mais é pausado antes. O `state_message` dele diz “paused early: its server's memory ran short”.
- **Pouco disco:** o servidor para os sandboxes PAUSED ociosos há mais tempo, “stopped early: its server's disk ran short”, e enquanto isso uma pausa vira parada, “stopped instead of paused”.
- **Disco esgotado:** o servidor para o sandbox RUNNING cujo disco mais cresceu, com o motivo CRASH, “its server ran out of disk space”. O disco dele é guardado.

Um sandbox que não está ocioso nunca é pausado antes da hora por falta de memória.

## O que acontece a seguir: next_state e os motivos

`GetSandbox` responde com `next_state` e `next_state_time`: o que o ciclo de vida faz com o sandbox a seguir se nada acontecer antes, PAUSED, STOPPED ou DELETED, e quando. Eles ficam ausentes enquanto algo mantém o sandbox acordado e quando nenhum timer corre no estado dele.

Toda mudança de estado tem um `state_reason`, e os eventos do sandbox mostram os mesmos motivos:

| Motivo | O que quer dizer |
| --- | --- |
| `REQUEST` | Uma chamada pediu. |
| `IDLE` | Um timer, ou o servidor com pouca memória ou pouco disco. |
| `WAKE` | Uma chamada, um login SSH ou uma requisição a uma porta o retomou. |
| `CRASH` | A VM ou o servidor falhou, ou ele não iniciou. Só `ResumeSandbox` o inicia de novo. |
| `MAINTENANCE` | A máquina do servidor reiniciou: pausado antes, sem cobrança, e rodando de novo depois. |
| `UNPAID` | Nada paga pelo espaço de trabalho: [cobrança](https://pethost.dev/pt/docs/sandboxes/billing/#unpaid). |

## Valores por caso de uso

São recomendações, feitas a partir das regras acima. Os timers estão em segundos, como a API os recebe.

| Caso de uso | Pausa | Parada | Exclusão | wake_when_stopped | keep_awake |
| --- | --- | --- | --- | --- | --- |
| A sessão de um agente, como o Claude Code na nuvem | `300`, o padrão | `0`, ou `86400` | `0` | Não | Em builds longos |
| Um sandbox por usuário do seu app de IA | `60` a `300` | `1800`, o padrão | `604800` | Se o seu app chama sem `ResumeSandbox` | Não |
| Um preview que dorme | `120` | `0` | `2592000` | Não | Não |
| Um job em lote ou um eval | `0` | `60` | `600`, ou `DeleteSandbox` no fim | Não | No comando do job |

O sandbox de um agente guarda os processos quando nunca para, e um dia pausado custa 30% de um dia rodando. Um preview sem timer de parada acorda com uma visita em cerca de 0,2 s, com o servidor de desenvolvimento onde estava. A [cobrança](https://pethost.dev/pt/docs/sandboxes/billing/#examples) calcula quanto custa cada um.

## Quando não funciona

- **Ele pausou durante um build longo.** Nada o chamou, e um build é um processo em segundo plano. Rode o build com `keep_awake`.
- **Uma chamada responde FAILED_PRECONDITION com Stopped.** O sandbox está STOPPED. Chame `ResumeSandbox`, ou ative `wake_when_stopped`.
- **Uma porta responde 503, “stopped: resume it”.** O mesmo, visto de um navegador ou do curl.
- **Uma chamada responde UNAVAILABLE com Restoring.** O disco está voltando do armazenamento de objetos, cerca de 10 s por GiB. Espere, ou chame `ResumeSandbox` de novo para acompanhar.
- **Ele pausou antes do timer.** O servidor ficou com pouca memória: o `state_message` diz isso. Ele acorda como sempre na próxima chamada.

## Perguntas

### Um processo em segundo plano mantém um sandbox acordado?

Não. Só chamadas, streams e links abertos, sessões SSH, requisições a portas, turnos de agente rodando e comandos iniciados com `keep_awake` mantêm. Um processo em segundo plano pausa com o sandbox e continua quando ele acorda.

### Como faço para um sandbox nunca parar?

Defina `stop_after_idle_seconds` como 0. Ele ainda pausa quando ocioso, o que guarda os processos, e acorda na próxima chamada.

### Como mantenho um sandbox rodando o tempo todo?

Defina `pause_after_idle_seconds` e `stop_after_idle_seconds` como 0, e ele roda até você pausá-lo, pará-lo ou excluí-lo, pelo preço rodando.

### Um sandbox parado acorda quando eu o chamo?

Só com `wake_when_stopped` ativado, e aí as vCPUs dele contam no seu plano enquanto ele está parado. Senão, `ResumeSandbox` o inicia.

### Sandboxes ociosos são excluídos automaticamente?

Não por padrão. Defina `delete_after_idle_seconds`, ou chame `DeleteSandbox` quando terminar.

[AnteriorConecte um agente aos sandboxes por MCP](https://pethost.dev/pt/docs/sandboxes/connect-an-agent/) [PróximaPreços e cobrança de sandboxes: por segundo, por estado](https://pethost.dev/pt/docs/sandboxes/billing/)

## Experimente o Pethost Agent Sandboxes

Um teste grátis de 7 dias com US$ 1 de uso e 4 vCPUs; é preciso um cartão. Depois, um plano a partir de US$ 20 por mês, que inclui esse mesmo valor em uso.

[Começar o teste grátis](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Templates](https://pethost.dev/pt/templates/)
- [Sobre nós](https://pethost.dev/about/)
- [Docs](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/pt/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Termos](https://pethost.dev/terms/)
- [Privacidade](https://pethost.dev/privacy/)
- [Reembolsos](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Bancos de dados

- [Postgres](https://pethost.dev/pt/postgres/)
- [Valkey](https://pethost.dev/pt/valkey/)

Agent Sandboxes

- [Sandboxes](https://pethost.dev/pt/sandboxes/)
- [Preços](https://pethost.dev/pt/sandboxes/#pricing)
- [Docs](https://pethost.dev/pt/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Comparativos

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/pt/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/pt/blog/coolify-cloud-vs-dokploy-cloud/)
- [Preços Railway vs Render vs Fly.io](https://pethost.dev/pt/blog/railway-vs-render-vs-fly-io-pricing/)
- [Hospedagem gerenciada de Docker Compose](https://pethost.dev/pt/blog/managed-docker-compose-hosting/)

Alternativas

- [Alternativas ao Railway](https://pethost.dev/pt/blog/railway-alternatives/)
- [Alternativas ao Heroku](https://pethost.dev/pt/blog/heroku-alternatives/)
- [Alternativas ao Dokploy](https://pethost.dev/pt/blog/dokploy-alternatives/)
- [Alternativas ao Coolify](https://pethost.dev/pt/blog/coolify-alternatives/)
- [Alternativas ao Render](https://pethost.dev/pt/blog/render-alternatives/)
- [Alternativas ao Sliplane](https://pethost.dev/pt/blog/sliplane-alternatives/)
