Your app addresses a sandbox with a sandbox ID. The Linux environment that runs commands and holds local files is a container. The ID can outlive any one container.
That distinction matters for processes, terminals, files, and recovery after idle stop or replace.
Most apps use one sandbox per user or task:
const sandbox = getSandbox(env.Sandbox, "user-123");const sandbox = getSandbox(env.Sandbox, "user-123");| Meaning | |
|---|---|
| Sandbox ID | The string you pass to getSandbox (for example "user-123"). Use the same ID to reach the same sandbox later. |
| Durable Object | The coordinator behind that ID. The same ID maps to the same Durable Object identity. |
| Container | The current Containers instance that runs Linux work for the sandbox. |
| Process or terminal | A program or interactive PTY inside the current container. |
| Local files | Files on that container’s disk (for example under /workspace). |
Same sandbox ID does not mean the same container. After the container stops or is replaced, the next work for that ID may run in a new container.
getSandbox() returns immediately. It does not start a container by itself.
The container starts when an operation needs it — for example exec(), createTerminal(), or writing a file. The first start after deploy or idle can take longer than a warm call. If the container is not ready yet, the SDK may throw ContainerUnavailableError. That error means the operation did not start inside the container. Refer to Errors and recovery.
While a container is up for a sandbox ID:
- Processes and terminals keep running until they exit or you stop them.
- Local files stay available in that container.
- Later Worker requests can call
getProcessorgetTerminaland continue, as long as that container still has the resource.
Process detail: How long a process lives. Terminals: Terminals.
A container is not permanent. Cloudflare may stop it after idle time. It can also stop after failures, or when the platform replaces it during normal operations (for example after some deploys).
When that happens:
- Your app still uses the same sandbox ID.
- Processes and terminals from the old container are gone, including their IDs and live log buffers.
- Local files from the old container are gone unless your app restored them (for example with a backup or a mounted bucket).
- The next real work may start a new container for the same sandbox ID.
- Handles from the previous container fail closed.
getProcessandgetTerminalreturnnullwhen the resource is not in the current container. Those lookups do not start a container only to answer the question.
To continue work later, store the job (what to run, cwd, env, and any app checkpoint), not only a process or terminal ID.
| Event | What stays | What is gone |
|---|---|---|
| Idle stop | Sandbox ID and Durable Object identity | Processes, terminals, local files from the stopped container |
| Replace (failure, deploy, or other replacement) | Sandbox ID and Durable Object identity | Same as idle stop for the previous container |
destroy() |
The sandbox ID string can be used again later | Treat prior work for that generation as finished |
After idle stop or replace, the next real work may start a new container for the same sandbox ID. Old process and terminal handles are invalid. Recovery procedures: Errors and recovery.
keepAlive and sleepAfter change idle behavior. They do not keep one container instance forever. Refer to the stable Lifecycle API and Sandbox options (ignore transport and default-session options on @next).
Only what your app keeps (or restores) survives a new container:
| Need | What must live outside the container |
|---|---|
| Find the sandbox again | The sandbox ID |
| Continue work on a later request | Resource ID while the current container still has it, plus enough job context to start again if it does not |
| Survive stop or replace | The job: command or terminal setup, cwd, env, checkpoint |
| Keep files after a new container | Backup metadata, mount configuration, or another durable store |