Sandbox Lifecycle

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

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 or preview port.
• 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. And note the flip side: anything that regularly sends requests to the sandbox, such as an external uptime check on a preview URL, will keep resetting the timer.

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. 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 effective settings and the tier each came from, run tektona sandbox get:

# Show effective values (and where each is inherited from)
tektona sandbox get <sandbox_id>

# 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) — snapshots 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 — snapshots 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.