Skip to content

Pause and resume

Pause a sandbox to preserve its memory, running processes, and files without paying while it's paused. Resume it later from where it left off, using the same sandbox ID.

This is useful for agents waiting between turns or workloads you want to continue later.

The examples use $SANDBOX for the sandbox ID, as in the quickstart.

Pause

curl -X POST https://sandbox.keln.ai/v1/sandboxes/$SANDBOX/pause \
  -H "Authorization: Bearer $KELN_API_KEY"

The API returns the sandbox with state set to paused and paused_at populated. Billing stops immediately, and the sandbox no longer counts toward the workspace's running sandbox limit.

Pausing usually takes about a second. The first pause may take around 2 seconds per GiB of memory.

If the sandbox is still starting, Keln waits until it's running before pausing it. Pausing an already paused sandbox returns 200 with no changes.

A sandbox can still be paused or stopped if its API key is blocked or its account is suspended.

While it is paused

While paused
Commands, files, terminals Requests return 409 sandbox_paused.
Preview ports Unavailable until the sandbox resumes.
Open connections, terminals, command streams Connections are closed and don't survive the pause.
Running commands Execution is suspended and continues from where it left off after resuming. The timeout_s timer is also paused.
Reading, listing, deleting the sandbox These operations remain available.

A workspace can have up to 100 paused sandboxes (429 paused_limit).

Paused sandboxes are retained for 30 days. After that, Keln stops them with end_reason set to pause_expired.

Keln stores a snapshot while the sandbox is paused. See Data handling for details.

An exhausted balance or API key budget doesn't affect a paused sandbox because it isn't consuming credits. A suspension of the account or API key, however, stops it.

Resume

curl https://sandbox.keln.ai/v1/sandboxes/$SANDBOX/resume \
  -H "Authorization: Bearer $KELN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"timeout_s": 3600}'

The sandbox resumes with the same memory, processes, and files. Billing starts again once it's running.

The API usually returns 200 with state set to running within a second. If resuming takes longer, it returns 202 with state set to starting. Requests sent during startup wait until the sandbox is ready.

Resuming an already running sandbox returns 200 without changing it.

Resuming has the same requirements as creating a sandbox:

  • An available slot within the workspace's running sandbox limit (429 concurrency_limit).
  • Enough balance to cover the first 5 minutes of runtime (402 insufficient_balance).

Expiry after a resume

The request body is optional.

The sandbox keeps its existing expires_at unless the new expiry, calculated as the current time plus timeout_s, is later.

If timeout_s isn't provided, the default is 300 seconds, the same as when creating a sandbox.

A sandbox can run for a maximum of 24 hours from its most recent resume.

Errors

Code Meaning
402 insufficient_balance Insufficient balance to cover the first 5 minutes of runtime.
409 sandbox_paused The sandbox is paused. Resume it first.
409 sandbox_resuming The sandbox is resuming. Wait until it's running before pausing it.
409 sandbox_not_running The sandbox has stopped and cannot be resumed.
429 concurrency_limit The workspace has reached its running sandbox limit. Stop or pause another sandbox.
429 paused_limit The workspace has reached its limit of 100 paused sandboxes. Delete or resume one.
503 pause_failed The sandbox couldn't be paused and is still running. Safe to retry.
503 resume_failed The sandbox couldn't be resumed and remains paused. Safe to retry.