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
| Setting | Default | What it does |
|---|---|---|
| Auto-pause | 15m | Pause the sandbox after this long with no activity. |
| Pause mode | hibernate | How it pauses — hibernate or suspend (see below). |
| Auto-resume | on | Wake the sandbox automatically on the next access. |
| Auto-delete | never | Off by default. Set a window to delete a paused sandbox that long after it was paused. |
| Run limit | 24h | Pause 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 inheritEach 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 inheritThe 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.