Sandbox Lifecycle
Understanding how Docker commands create, use, and destroy sandboxes.
Lifecycle Stages
1. Creation
When you run docker run, FactorySandbox creates a new isolated sandbox from the image you requested.
2. Ready
Once ready, the sandbox behaves like a Docker container. You can execute the command from your image, inspect running sandboxes, and stream logs through Docker.
3. Active
During active use, the sandbox keeps the process, filesystem changes, and environment for that container until the container exits or is removed.
4. Idle Timeout
Long-running sandboxes are subject to runtime limits. Use docker psto see active work and remove sandboxes you no longer need.
5. Destruction
Sandboxes are destroyed when the container exits, when you remove them withdocker rm, or when the runtime enforces a limit. Ephemeral sandbox data is deleted.
Timeouts
| Timeout Type | Default | Max | Description |
|---|---|---|---|
| execution | Plan dependent | Plan dependent | Maximum runtime for a sandbox command |
| idle | Plan dependent | Plan dependent | Time before inactive work is cleaned up |
| session | Plan dependent | Plan dependent | Max total sandbox lifetime |
State Persistence
Sandboxes are ephemeral by default. All filesystem changes inside the sandbox are lost when it is destroyed. Persist anything important outside the sandbox before the process exits.
- External storage - Write artifacts to your own storage during execution
- Output capture - Capture stdout and stderr from Docker logs
- Image contents - Put required tools and files in the base image you run
Best Practices
- Remove long-running sandboxes when you are done with them
- Use appropriate timeouts for your use case
- Use images that already contain the tools your agent needs
- Capture logs and artifacts before the sandbox exits