Skip to content

Sandbox lifecycle

A sandbox's state is one of starting, running, paused, deleted, error. Every change of state is one of the moves below: a call you make, or Runtime's own when the machine starts, stops or is lost.

From To By
(new) starting create
starting running Runtime
starting error Runtime
running, starting paused pause
running paused Runtime
paused starting resume
running starting Runtime
starting, running, paused, error deleted delete
Updated .md

What to do in each state#

  • POST /v2/sandboxes/{id}:exec resumes a paused sandbox first, so a paused sandbox needs no resume call before a command.
  • POST /v2/sandboxes/{id}:pause keeps the sandbox's disk and stops its CPU and memory billing. POST /v2/sandboxes/{id}:resume starts it again. See pause and resume.
  • DELETE /v2/sandboxes/{id} ends a sandbox in any state. Delete every sandbox you no longer need: a paused sandbox still pays for its storage.
  • A error sandbox failed to start and can only be deleted. Create a new one, from a snapshot if you keep its state.
  • A starting sandbox is being made, resumed, or started again on another server after its own stopped answering; wait for running.
  • A deleted sandbox is in a delete's answer alone: a get of a deleted sandbox is 404, and no list shows one.

No time limit#

A sandbox has no time limit: it runs until it pauses or is deleted. idlePauseSeconds: Seconds with nothing happening before it pauses; 0 never.

Spending limits#

maxCost: The most it may cost in all, in US dollars ("5.00"): once it has cost that it pauses, and starts again only once its maxCost is raised (update); what a key's per-request and spend caps count. When omitted under a key with a per-request or spend cap, the most that key's caps leave.

Give this to your agent#

Paste this into your coding agent:

Read https://withruntime.com/docs/lifecycle.md. Check this project's Runtime code handles every sandbox state it can meet, and that every sandbox it creates is deleted on every path, failures included.

This page as Markdown: https://withruntime.com/docs/lifecycle.md

Try it on your own work.Signing up takes no card. Your first sandbox asks for one, and the trial starts then. Or paste the setup prompt into your agent.
Start your free trial