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 afteridle_timeout_swithout requests. Sandboxes started by AI assistants over MCP usepauseby default. - A sleeping sandbox is kept for 7 days without use, then deleted.
DELETEdeletes 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 hasname,last_used,slept_at,woken_atanddisk_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 (
409otherwise). - 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
503with codesandbox_unavailable; try again shortly. A new, empty sandbox is never created in its place.
Sleep or pause?
| Sleep | Pause | |
|---|---|---|
| Files | kept | kept |
| Memory and running programs | not kept – programs start again | kept – continues exactly where it stopped |
| Compute billed | no | no |
| Good for | coming back to a project later, between chats | a short break between turns of a conversation |