What you will build
A lifecycle journal that distinguishes creation, an agent session, execution, stopping and deletion. These are separate events with different effects on files and resource use.
- Create a named sandbox
- Run or exec starts it
- Stop preserves state
- Export, then remove
Conceptual flow. Follow the lesson for prerequisites, exact commands and verification limits.
Read the mechanism
sbx create prepares an environment without attaching to the agent. Local creation can finish with the sandbox stopped once no sessions keep it alive. sbx exec starts a stopped sandbox when needed; sbx run --name attaches to the configured agent. A stopped sandbox still exists.
A detached sbx run -d keeps a local sandbox running beyond an attached session. Do not use it merely because you want a stable name. Background services and published ports make detached mode useful, but they also make “I closed the terminal” a poor cleanup strategy.
sbx rm deletes in-sandbox state. It does not roll back edits already written to a directly mounted host workspace. Model session history, VM state, source changes and billable cloud runtime each have separate lifecycles.
Worked lab · prove persistence
Create a fresh mountless shell sandbox. Naming it explicitly avoids accidentally reusing the first chapter’s direct mount:
sbx create --name handbook-lifecycle shell
sbx ls
sbx exec handbook-lifecycle sh -c 'printf "keep me\n" > /tmp/lifecycle-note'
sbx stop handbook-lifecycle
sbx ls
sbx exec handbook-lifecycle cat /tmp/lifecycle-note
sbx lsRecord the status before and after each operation. The final exec may start the sandbox and the runtime may stop it again when its session ends. A transient status is not evidence that your file was lost.
To practice an agent attachment interactively, use sbx run --name handbook-lifecycle, then leave the shell normally. For automation, prefer a bounded command with exec and check its exit code.
Expected observations
The marker survives a stop/start cycle. Its persistence should not depend on your host’s current directory. The same named sandbox supplies the stored environment.
When you are finished, export the harmless marker into a new local output directory:
mkdir handbook-lifecycle-output
sbx cp handbook-lifecycle:/tmp/lifecycle-note ./handbook-lifecycle-output/Inspect the exported file before optional cleanup. Only after confirming this is your disposable sandbox, run sbx rm handbook-lifecycle and read its confirmation prompt. Avoid global reset or prune commands in a learning exercise.
Troubleshooting
A reused name may refer to a different earlier task. Check sbx ls rather than assuming “create” always produced a clean environment. If removal is refused because a session is active, close that session deliberately; do not automatically force deletion. A missing host export is a reason to stop cleanup.
Interview practice
What is the difference between stop and remove?
Stop preserves the sandbox’s files and configuration while ending its running state. Remove destroys the environment and its private work. Neither is a rollback mechanism for direct host writes.
Why should a controller track sandbox IDs separately from human task names?
Names are convenient but can be reused. An explicit run record needs a stable resource identity, ownership and terminal state to avoid cleaning up the wrong environment.
Completion check
Show one file surviving stop/start, explain the status transitions, and identify the evidence export that must precede deletion.
Sources and version notes
Checked 6 October 2026; current baseline: sbx v0.46.0. Get started locally · sbx exec · Docker Sandboxes v0.46.0 release
Make the understanding yours.
Use the completion check above. Mark this chapter when you can explain the mechanism and its limits.
Self-assessed reading progress. This does not certify that a lab ran or a system is secure.