Idle is measured at the boundary, not inside the box
Why BoxLite Cloud watches the boundary of a box instead of its workload, and the two failure modes that follow from it.
A BoxLite Cloud box stops when it goes idle and wakes when something touches it. The part worth understanding before you design around it is what "touches" means: idle is measured at the box's boundary, not by what the box is doing. That single choice is what makes wake-on-access possible, and it is also the source of the two ways teams get surprised by it.
When you create a box in the console you set three switches: Stop when idle, Wake on access, and Delete after stopping. A stopped box wakes on SDK exec, file operations, or a terminal attach. So the agent's home comes back on demand instead of burning compute while nothing is asking it to work.
That is the pitch, and it holds. But the definition underneath it is narrower than most people assume.
What counts as activity
From the Cloud docs, verbatim:
idle means no SDK, terminal, or preview traffic. Work running inside the box does not count, so a long job can be stopped mid-run.
Read that twice. The idle timer is driven by traffic crossing into the box. A for loop pegging the CPU for forty minutes with nothing calling in is, as far as the lifecycle is concerned, silence.
This is not an oversight. It falls out of what wake-on-access requires. To wake a stopped box you have to be watching something that still exists while the box does not — an inbound request, a file operation, a terminal attach. You cannot watch a process inside a VM that is not running. Once the signal has to live at the boundary for wake to work, the same signal is the cheapest thing to reuse for stop. Symmetry, not laziness.
The cost of that symmetry is that internal work is invisible to the thing deciding whether you are done.
Failure mode one: the long job that gets cut
An agent that installs a toolchain, kicks off a build, and then waits is doing exactly the kind of work that looks like nothing from outside. If the idle window is shorter than the build, the box stops mid-run.
Two ways out, and they are not equivalent:
- Set the idle switches deliberately for that box. Long-running work is a per-box decision, not a global default.
- Make a mid-run stop survivable instead of preventing it. Mount a managed volume and write progress to it. A box loses everything on its disk when it is destroyed; a volume does not, and another box can mount it later. A job that checkpoints is a job you are allowed to interrupt.
The second is the more durable answer. Tuning a timeout to be longer than your longest job is a bet you will eventually lose.
Failure mode two: treating it as a budget
The billing docs are blunt about this one:
Treat stop-when-idle as a safety net, not a budget. A busy box is never idle, so stop-when-idle will not cap what it spends.
Idle-stop protects you from the box you forgot. It does nothing about the box that is genuinely in use, because that box is never idle by definition. If a runaway agent is hammering a box in a loop, every one of those calls is traffic, and traffic is the opposite of idle.
Pay-as-you-go is metered per hour across three dimensions: $0.0504 per vCPU-hour, $0.0144 per GiB-hour of memory, and $0.00018 per GiB-hour of disk. The smallest box (1 vCPU, 1 GiB, 10 GiB) comes to $0.0666 an hour. Those rates do not care why the box is up.
The habit the docs recommend is the unglamorous one: remove boxes when the work is done, as part of the task rather than as cleanup you plan to get to later.
What this buys you
The reason to accept a boundary-measured lifecycle is the second shape of box it enables. A disposable box for untrusted code does not need any of this; you create it, run, and remove it. But a persistent home for an agent does. It installs its tools once, writes files, stops, and picks the work back up later instead of rebuilding its world on every run.
Keeping that box up around the clock so it is warm when needed is the naive version, and you pay for every idle hour of it. Stop-and-wake gets you the same continuity without the standing bill, precisely because something at the boundary is still listening while the compute is not.
Design for it explicitly:
- Decide per box whether its work is externally driven or internally driven. Internally driven work needs the idle switches set, not defaulted.
- Put anything you would hate to lose on a volume, not on the box disk.
- Use idle-stop as a backstop for forgotten boxes. Use teardown as your cost control.
The lifecycle is managed. Which things count as life is still your call.