> ## Documentation Index > Fetch the complete documentation index at: https://instabox.sh/docs/llms.txt > Use this file to discover all available pages before exploring further. # Auto-pause and max-run > When a machine pauses by itself, what wakes it, and the cooldown after a maximum runtime. A running machine pauses once it has been idle for 30 minutes, and wakes on the next use, with its memory and processes kept. ```bash theme={null} instabox auto-suspend job 10m # pause after 10 idle minutes instabox auto-suspend job 0 # never pause when idle ``` * **Paid plans**: any whole minute from 5 to 30, or `0` to turn it off. A part minute, or a value outside that range, is refused. * **Free plan**: fixed at 30 minutes. Another value is refused. The setting stays across pause and resume. To set it at create, use `--auto-suspend` (`autoSuspendAfterSeconds`). ## What counts as idle Idle means no coding agent working, no terminal or SSH traffic, and no CPU load. An exec, a file read, a public port request, or a task lease in progress keeps the machine busy. When a signal is missing or unclear, the machine counts as busy. ## Keep a machine awake during a silent task A task that waits without output (for example on a model API) can still be paused as idle. To keep the machine awake, hold a lease: ```text theme={null} PUT /v1/machines/{id}/activity-leases/{taskID} # body {"ttlSeconds": 300}, 30-3600 DELETE /v1/machines/{id}/activity-leases/{taskID} # release it ``` Renew the lease before `ttlSeconds` runs out. ## What wakes a machine A machine that paused **itself** (`autoSuspendedAt` set) resumes on use. A request that wakes it waits up to 45 seconds for the resume, then runs. If the resume is still running after that, the answer is a retryable `409 operation_conflict` naming the operation. Rows that differ say so. | Action | Wakes it? | Notes | | - | - | - | | `instabox exec` (`POST /v1/machines/{id}/exec`) | Yes | Waits for the resume. | | `instabox ps` (`GET /v1/machines/{id}/processes`) | Yes | Waits for the resume. A machine you paused or stopped shows the list read before it went down. | | List, read, or write files (`GET /v1/machines/{id}/files`, `GET .../files/content`, `PUT .../files`) | Yes | Waits for the resume. A signed upload URL wakes it when used, not when created. | | `instabox ssh`: the certificate request (`POST /v1/machines/{id}/connections`) | Yes | Waits for the resume. | | An SSH connection through the gateway, with a certificate or an SSH token | Yes | Waits up to 15 seconds. If the resume is still running, the connection is refused with `machine ... is waking up; try again in a few seconds`. | | A request to a public port URL (HTTP) | Yes | The request waits for the resume. If the resume is still running, the answer is `503` (Sandbox is waking up) with `Retry-After`. | | A raw TCP connection to a public port | Yes | The connection waits up to 45 seconds for the resume. If the resume is still running, or the machine cannot run, the server closes the connection after the TLS handshake with no answer. Connect again. Once open, it counts as activity only while bytes flow. | | A request to a private port without its token | No | Refused with `401` (`403` for a wrong `_token`) without waking it. | | The dashboard's **Computer** or **Files** tab | Yes | Opening the tab sends `POST /v1/machines/{id}/wake`. | | The dashboard terminal (`GET /v1/machines/{id}/terminal`) | Yes, when you open it | Its automatic reconnects send `wake=0` and get a retryable `409 machine_not_running` instead. | | Desktop `install`, `start`, `takeover`, or `handback` (`POST /v1/machines/{id}/desktop`) | Yes | On a template whose desktop is the VM's own screen, these return `409 machine_not_running` instead. | | Desktop `status`, or the desktop stream (`GET /v1/machines/{id}/vnc`) | No | `409 machine_not_running`. | | `instabox wake` (`POST /v1/machines/{id}/wake`) | Yes | Waits for the resume. Counts toward the plan's starts a minute. | | Take a lease (`PUT /v1/machines/{id}/activity-leases/{taskID}`) | Yes | Waits for the resume. Releasing a lease (`DELETE`) does not wake it. | | MCP `exec`, `read_file`, or `write_file` | Yes | Runs the REST route above, so it waits the same way. | | `instabox get`, `instabox ls`, `instabox logs`, exec history (`GET /v1/machines/{id}/history`) | No | Reads what the server stored. | A GitHub Actions job keeps its CI machine awake while the job runs. It does not wake a paused one. > [!NOTE] > > A machine **you** paused or stopped does not wake on use, `instabox wake` included: run > `instabox resume` or `instabox start`. Until then its public URLs return `503` (Sandbox offline), with > the command to run in the body. ## Set a maximum runtime `maxRunMinutes` pauses a machine after that many minutes of continuous running, **even while it is busy**. Explicit runtime settings and the default fixed limit are not extended by activity or leases. ```bash theme={null} instabox max-run job 120 # pause after 120 running minutes instabox max-run job -1 # unlimited ``` * `-1` is unlimited. `0` pauses the machine at once and keeps it from waking until you change the setting. * Free machines default to 480 minutes at a time. The service manages this limit; only an admin can override it. Dynamic runtime, when enabled, follows the rules below. * Paid machines default to `-1`. Set it at create (`--max-run-minutes`) or later with `instabox max-run` or `PATCH /v1/machines/{id}`. Whichever comes first, idle pause or maximum runtime, pauses the machine. The next wake starts a fresh run. ### Dynamic runtime on the free plan Each new run starts with a 2-hour window. Five minutes before its deadline, the service checks the preceding 30 complete minutes of work: | Distinct minutes with work | Change to the current deadline | | - | - | | At least 5 | Extend by 2 hours | | 1 to 4 | Extend by 30 minutes | | 0 | Pause at the current deadline | Exec and file requests, app requests, terminal or SSH traffic, and guest activity count as work. Renewing a keepalive lease or requesting a wake does not earn an extension. If activity cannot be collected reliably, this run uses an 8-hour limit measured from its start. Every run pauses by 8 hours, even with continuous work. The normal idle pause can happen earlier. For example, a run started at 09:00 initially ends at 11:00. At 10:55, five working minutes extend that deadline to 13:00; two working minutes extend it to 11:30. If collection is unavailable, the deadline becomes 17:00, which is also the absolute latest deadline with continuous work. `instabox get` reports the current limit as `maxRunMinutes`, measured from `runStartedAt`. A pause and subsequent wake start a fresh window; a max-run pause still applies the existing cooldown. ## Cooldown after a maximum runtime A pause for maximum runtime starts a cooldown. An idle pause has none. The cooldown is 5 minutes plus a random 0 to 15, so machines that reach their limit together do not all wake together. > [!WARNING] > > Until the cooldown ends, every way of waking or starting the machine (exec, SSH, file reads, public > URLs, wake, resume, and start) is refused with `409 machine_cooldown`. Stopping, pausing, or changing > settings does not shorten a cooldown already started. The refusal is `retryable: true`, with a `Retry-After` header and `retryAfterSeconds` in the body. Both give the seconds left. The machine's `cooldownUntil` (`instabox get`) says when the cooldown ends, and `instabox ssh` prints it. Wait that long, then retry. After the cooldown, a machine whose `maxRunMinutes` is `0` still refuses to wake with `409 max_run_disabled` until you change the setting. > [accordion] Longer cooldowns on the free plan > > On the free plan, back-to-back max-run pauses rest longer. By default: > > | Max-run pause in a row | Cooldown | > | - | - | > | 1st | 5 to 20 minutes | > | 2nd | 60 to 75 minutes | > | 3rd and later | 120 to 135 minutes | > > Each step is a base (5, 60, or 120 minutes) plus the same random 0 to 15. The count starts over when > a run ends with no cooldown owed (an idle pause, or you pause or stop the machine). It also starts > over when a run starts 2 hours or more after the last cooldown ended. A new or forked machine starts > at the 1st step. Restoring a machine in place keeps its count. A machine on a paid plan always gets the 1st step. The > length is fixed when the pause starts, and `cooldownUntil` says exactly when it ends. > [accordion] Lock after a security check > > A lock after a security check paused the machine is not a max-run step, and it can last up to 24 > hours. The lock is a cooldown, so it keeps the count. A run started less than 2 hours after the lock > ends continues the count, and that run's max-run pause can get the 2nd or 3rd step. > [card] [Lifecycle](https://instabox.sh/docs/machines/lifecycle.md) > > Pause, resume, stop, and start by hand. > [card] [Storage and retention](https://instabox.sh/docs/machines/storage.md) > > What is kept, for how long, and the archive and delete deadlines.