> ## Documentation Index > Fetch the complete documentation index at: https://docs.polpo.sh/llms.txt > Use this file to discover all available pages before exploring further. # Sandboxes > Control how agent runs acquire, share, retain, and release isolated workspaces. Sandboxes give agents an isolated workspace for files, code, browser sessions, and tools. A writable local workspace is available automatically. Configure three independent behaviors: * `isolation` controls which sandbox a run acquires. * `lifecycle` controls what happens to that sandbox after the run ends. * `volumes` optionally narrows the agent's persistent-volume grants for one run. ```json theme={null} { "sandbox": { "isolation": "fresh", "volumes": [ { "name": "reference", "access": "read-only" } ], "lifecycle": { "onRelease": "pool", "stopAfterIdleMinutes": 30, "deleteAfterStopMinutes": 60 } } } ``` This example starts from a clean sandbox, attaches only the granted `reference` volume as read-only, keeps one lease for the entire run, returns it to the pool, stops compute after 30 idle minutes, and deletes sandbox storage 60 minutes after the stop. ## Isolation | Mode | Behavior | Use it for | | -------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------ | | `reuse` | Acquires an exclusive compatible sandbox from the project pool when available. | Fast repeat runs and normal development workflows. | | `fresh` | Creates a clean sandbox for the outer run. | Untrusted inputs, clean builds, and reproducible tests. | | `shared` | Uses a project-scoped sandbox that concurrent outer runs may intentionally share. | Coordinated runs that must work in the same live filesystem. | `reuse` never gives the same sandbox to concurrent outer runs. A sandbox only becomes reusable after its current lease has been released. `fresh` creates one sandbox for the whole outer request. Root tool calls, deterministic loop steps, and nested agent steps all use that same filesystem until the request or task finishes. Use `shared` only when concurrent runs are expected to collaborate. They can read and modify the same files, so your workflow must handle write conflicts. ## Lifecycle | Setting | Behavior | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | | `onRelease: "pool"` | Returns the sandbox to the project pool when the outer run finishes. | | `onRelease: "destroy"` | Deletes the sandbox when the outer run finishes. | | `stopAfterIdleMinutes` | Stops pooled sandbox compute after this many idle minutes. Accepts an integer from `1` to `10080` (seven days). | | `deleteAfterStopMinutes` | Deletes sandbox storage this many minutes after it stops. Accepts an integer from `0` to `10080`; `0` keeps stopped storage. | Lifecycle timers only apply to `onRelease: "pool"`. Combining either timer with `onRelease: "destroy"` is invalid. The deprecated `idleTtlMinutes` field is accepted for compatibility and maps to stop-after-idle with stopped storage retained; do not combine it with the explicit fields. ## Common policies | Policy | Configuration | Result | | ------------------------- | -------------------- | ------------------------------------------------------------------------------------ | | Warm and exclusive | `reuse` + `pool` | Reuse an idle sandbox when possible, then return it to the pool. | | Warm but disposable | `reuse` + `destroy` | Reuse an idle sandbox when possible, then delete it. | | Clean and retained | `fresh` + `pool` | Start clean, then retain the sandbox for a later run. | | Clean and disposable | `fresh` + `destroy` | Start clean and delete the sandbox when the run ends. | | Concurrent and retained | `shared` + `pool` | Concurrent runs share one workspace, which remains available afterward. | | Concurrent and disposable | `shared` + `destroy` | Concurrent runs share one workspace, which is deleted after its leases are released. | If `sandbox` is omitted, Polpo uses `reuse` and returns the sandbox to the pool. ## Precedence Polpo resolves each sandbox field independently, from lowest to highest precedence: 1. project settings 2. agent configuration 3. task or request payload A request can therefore override only `isolation` while inheriting the agent's lifecycle. Persistent volume selection is stricter: higher-precedence settings may remove volumes or narrow access/writeback, but cannot add an ungranted volume or widen its policy. ## Persistent volumes The local workspace is implicit and is not represented by a `local` volume mode. Project volumes use only `mounted` or `hydrated` strategy. Agents receive explicit grants; requests and tasks can select a narrower subset by name: ```json theme={null} { "sandbox": { "volumes": [ { "name": "workspace", "writeBack": "manual" } ] } } ``` For a manually managed hydrated volume, the runtime exposes `sandbox_volume_checkpoint`. Root steps and nested agent steps share the same outer lease, so a checkpoint sees all filesystem changes made earlier in that run. Finalization occurs once, before the Run becomes terminal. `shared` isolation supports mounted volumes. Hydrated volumes are rejected with `shared` because independent hydrate/writeback cycles cannot safely share one live filesystem. See [Storage](/docs/platform/storage) for volume creation, grants, writeback, and revision conflict behavior. ## Configure an agent Use an agent policy as the default for every run assigned to that agent: ```json theme={null} { "name": "qa-agent", "allowedTools": ["read", "write", "bash"], "sandbox": { "isolation": "fresh", "lifecycle": { "onRelease": "destroy" } } } ``` ## Override one chat request ```json theme={null} { "agent": "qa-agent", "messages": [ { "role": "user", "content": "Run the test suite" } ], "sandbox": { "isolation": "fresh", "lifecycle": { "onRelease": "pool", "stopAfterIdleMinutes": 30, "deleteAfterStopMinutes": 60 } } } ``` ## Configure a task ```json theme={null} { "title": "Run migration tests", "description": "Apply the migration on a clean workspace and report failures.", "assignTo": "qa-agent", "sandbox": { "isolation": "fresh", "lifecycle": { "onRelease": "destroy" } } } ``` The same `sandbox` object is available in schedule execution settings. ## Observe sandbox activity Sandbox lifecycle events are attached to the canonical Run trace. The Events timeline shows acquisition, resume, release, rejection, and failure events with their sandbox ID and timestamp. This is consistent across direct chat, tasks, Agentic Loops, channel messages, and scheduled executions because those are execution surfaces of the same Run model. For chat integrations, retrieve the transcript and its correlated Run traces together: ```http theme={null} GET /v1/chat/sessions/{sessionId}/activity ``` The response includes `messages` and a minimal `runs` projection. Runtime configuration, checkpoints, and other private execution state are not exposed by this endpoint. ## Files and persistent state Sandbox policy controls compute and the implicit local workspace. Persistent volumes, memory, Connections, task state, and chat sessions follow their own persistence rules. On Polpo Cloud, the managed sandbox provider implements pooling, TTLs, and project-scoped sharing. In self-hosted deployments, the configured provider decides how these policies map to local processes, containers, or another sandbox service.