Sandbox Lifecycle

How sandboxes auto-pause when idle, wake on access, and can auto-delete — and how to change the defaults per sandbox or per project.

Sandboxes manage their own lifecycle so you don't pay for idle time or leave environments running forever. By default a sandbox pauses after 15 minutes of inactivity and wakes automatically the next time you use it. Auto-delete is off by default: paused sandboxes are kept until you delete them, but you can optionally delete paused sandboxes after a retention window you set — per sandbox or per project.

The defaults

SettingDefaultWhat it does
Auto-pause15mPause the sandbox after this long with no activity.
Pause modehibernateHow it pauses — hibernate or suspend (see below).
Auto-resumeonWake the sandbox automatically on the next access.
Auto-deleteneverOff by default. Set a window to delete a paused sandbox that long after it was paused.
Run limit24hPause the sandbox after it ran this long without a pause, whatever its activity. Set by the cluster operator.

What counts as activity

The idle timer tracks real use, not just an open connection. Any of these resets it:

  • A live SSH, VNC, or terminal session — including one that's connected but sitting idle at the prompt.
  • HTTP traffic to a forwarded port or to a preview URL with a token. Traffic to a public preview URL does not count.
  • Agent activity — requests to and events from an agent running in the sandbox.
  • Outbound network transfers — actual data leaving the sandbox.

The timer counts traffic that crosses the sandbox boundary — it never looks inside the VM. Work that stays entirely internal (a long computation, a local cron job) is invisible to it and won't keep the sandbox awake; an unattended job that talks to the network does keep it awake while data is flowing. Connections that are merely open but silent — an attached agent that isn't exchanging messages, an idle TCP connection — don't count either. If you run silent, compute-only jobs, set auto-pause to never. The sandbox still pauses at the run limit. And note the flip side: anything that regularly sends requests to the sandbox, such as an external uptime check on a preview URL with a token, will keep resetting the timer.

Run limit

No sandbox runs without a bound. The run limit pauses a sandbox after it runs this long without a pause, even when it is in use and even when its auto-pause is never. The default is 24 hours. The cluster operator sets it, from 1 to 168 hours, in the Management Console.

  • The pause uses the sandbox's pause mode. A hibernate keeps the running processes. A suspend keeps the disk only.
  • The pause happens at or shortly after the run deadline.
  • A resume starts a new run with the full run limit. A reboot does not.
  • With auto-resume on, the next access wakes the sandbox again.
  • A pause at the run limit starts the auto-delete window, as an idle pause does. With auto-delete set, a sandbox that nobody resumes is deleted that long after the pause, even when its auto-pause is never.

tektona sandbox get shows the Run deadline of a running sandbox. The console shows it on the sandbox details page. The API returns it as lifecycle.run_deadline, next to lifecycle.running_since.

If an unattended job must run longer than the run limit, split it or save its progress, so that it can continue after a resume.

Waking a paused sandbox

With auto-resume on (the default), you don't have to resume manually — opening an SSH or VNC session, loading a preview URL, or sending an agent request to a paused sandbox resumes it automatically and then serves your request. A warm resume is typically sub-second, so the wake is nearly invisible. A public preview URL does not wake a paused sandbox: it answers 503 with sandbox is paused until the sandbox runs again. Turn auto-resume off if you want a paused sandbox to stay paused until you resume it explicitly.

Changing the settings for one sandbox

tektona sandbox lifecycle updates a sandbox's own overrides. To see the automatic actions, run tektona sandbox get. Use JSON output to inspect configuration sources:

# Show automatic actions in plain language
tektona sandbox get <sandbox_id>
tektona sandbox get <sandbox_id> --output json

# Pause after 30 minutes instead of 15; keep everything else
tektona sandbox lifecycle <sandbox_id> --auto-pause 30m

# Never auto-pause this sandbox (e.g. it runs an unattended job)
tektona sandbox lifecycle <sandbox_id> --auto-pause never

# Go back to inheriting the project / platform default
tektona sandbox lifecycle <sandbox_id> --auto-pause inherit

Each flag accepts one of three values:

  • a value — e.g. 15m, 30d, hibernate, suspend, true, false.
  • never — disable the timer (interval settings only).
  • inherit — clear this sandbox's own value and fall through to the project default, then the platform default.

Flags you omit keep their current value. The console exposes the same controls on the sandbox's settings page.

You can also set these on tektona sandbox create — it takes the same --auto-pause, --auto-pause-mode, --auto-resume, and --auto-delete flags, and any you omit inherit the project/platform default.

Setting project-wide defaults

Project defaults apply to every sandbox in the project that doesn't override the setting itself. Use them to, for example, disable auto-pause for a whole project or turn on an auto-delete window:

# Show a project's lifecycle defaults
tektona project lifecycle-defaults <project> --org <org>

# Pause project sandboxes after 1 hour and delete 7 days after pause
tektona project lifecycle-defaults <project> --auto-pause 1h --auto-delete 7d

# Clear a project default so its sandboxes use the platform default again
tektona project lifecycle-defaults <project> --auto-delete inherit

The settings resolve in three tiers — per-sandbox override → project default → platform default. Anything left as inherit falls through to the next tier down, so the platform defaults at the top of this page apply whenever nothing overrides them.

Hibernate vs. suspend

Auto-pause can pause a sandbox in one of two modes, which trade storage cost against resume speed:

  • Hibernate (default) — saves the sandbox's memory as well as its disk. Running processes survive and it resumes to exactly where it left off, usually in under a second. It stores a compressed RAM dump in addition to the disk, so it costs a little more storage while paused.
  • Suspend — saves the disk only. It's cheaper to store while paused, but the sandbox cold-boots on resume: processes are gone and it re-runs its entrypoint.

Set the mode per sandbox or per project with --auto-pause-mode hibernate or --auto-pause-mode suspend.

A hibernate whose memory image cannot be completed finishes as a suspend instead: the sandbox and its disk are kept, but its running processes are not. The sandbox ends up in suspended rather than hibernated, and its transition history gives the reason as partial_memory_image.

A hibernated sandbox resumes only on a runner node whose CPU can restore its memory. When no such node has room, the resume fails with a no-capacity error, and the sandbox stays hibernated with its memory. To start it without its memory, run tektona sandbox resume <sandbox-id> --discard-memory. The sandbox keeps its ID and boots from its disk on any node with room, like a suspended sandbox. Its running processes and memory contents are lost. The transition history gives the reason as discard_memory_requested.

If that resume fails after a runner node got it, the sandbox is suspended without its memory. The error says so. To try again, run tektona sandbox resume <sandbox-id> without --discard-memory. If it fails before any runner node gets it, the sandbox stays hibernated with its memory. When the disk is still on the node that hibernated the sandbox only, and that node is unavailable or full, the resume fails and the memory is kept.

Paused sandboxes keep their disk (and, when hibernated, their memory image) in storage until they're resumed or deleted. Set an auto-delete window to stop that storage accumulating for environments you've forgotten about.

On this page