WBX Sandbox
Sandboxes

Sleep and wake

A sleeping sandbox keeps its files on the server's disk while its virtual machine is stopped – compute is not billed. The first request wakes it up in a few seconds, with the same ID.

How it works

Running programs end and memory is not kept while a sandbox sleeps. The first request to a sleeping sandbox – a command, a file operation or resume – wakes it up: it boots from its own disk, which takes a few seconds, keeps its ID, and its environment variables and network settings are applied again. Start any programs you need again (a web server, for example).

from wbxsandbox import Sandbox

# the same name returns the same sandbox – also in a later chat or a later run
sb = Sandbox.create(template="base", name="my-project", on_timeout="pause", idle_timeout=600)
sb.files.write("/home/user/notes.txt", "keep me")
sb.sleep()                                       # or just stop using it

sb = Sandbox.create(template="base", name="my-project")   # wakes it up
print(sb.files.read_text("/home/user/notes.txt"))
curl -s -X POST https://sandbox.wbx.cz/v1/sandboxes -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"template": "base", "name": "my-project", "on_timeout": "pause", "idle_timeout_s": 600}'

curl -s -X POST https://sandbox.wbx.cz/v1/sandboxes/SB_ID/sleep -H "Authorization: Bearer YOUR_API_KEY"
curl -s -X POST https://sandbox.wbx.cz/v1/sandboxes/SB_ID/resume -H "Authorization: Bearer YOUR_API_KEY"

Details

  • A sandbox falls asleep with POST …/sleep, and – with "on_timeout": "pause" – when its lifetime ends or after idle_timeout_s without requests. Sandboxes started by AI assistants over MCP use pause by default.
  • A sleeping sandbox is kept for 7 days without use, then deleted. DELETE deletes it at once.
  • After a longer sleep (a day by default) a sandbox may be moved to long-term storage; its state is then "archived". It behaves the same way – the first request wakes it up, it just takes longer (the disk is copied back to a server first). Its ID stays the same.
  • Its state is "sleeping" ("falling_asleep" and "waking" while it changes); the object also has name, last_used, slept_at, woken_at and disk_bytes. It does not count towards your concurrent-sandbox, vCPU or memory limits.
  • The lifetime of a woken sandbox starts again from the moment it woke up. To change the lifetime of a sleeping sandbox, wake it first (409 otherwise).
  • Public URLs of ports do not wake a sandbox (409 sandbox_sleeping). A suspended account cannot wake sandboxes (402).
  • If it cannot be woken up right now – the server is full, for example – you get 503 with code sandbox_unavailable; try again shortly. A new, empty sandbox is never created in its place.

Sleep or pause?

SleepPause
Fileskeptkept
Memory and running programsnot kept – programs start againkept – continues exactly where it stopped
Compute billednono
Good forcoming back to a project later, between chatsa short break between turns of a conversation