> ## 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.

# Runtime Sandboxes

> Choose whether agent work reuses a warm sandbox or starts fresh.

Polpo carries sandbox isolation as a runtime policy. The same field can be set
on agents, tasks, or a single chat/task execution request:

```json theme={null}
{
  "sandbox": {
    "isolation": "reuse"
  }
}
```

`reuse` is the default. It lets the host reuse a warm project sandbox when one
is available, which keeps normal coding, browser, and file workflows fast.

`fresh` asks the host for a clean sandbox for that run. Use it for untrusted
inputs, tests that must not inherit process state, or workflows where isolation
is more important than startup latency.

## Precedence

The runtime resolves sandbox policy from lowest to highest precedence:

1. project/runtime settings
2. agent configuration
3. task or request payload

That means an agent can default to fresh execution, while a specific request can
override it back to reuse, or vice versa.

## Where to set it

Agent default:

```json theme={null}
{
  "name": "qa-agent",
  "allowedTools": ["read", "write", "bash"],
  "sandbox": {
    "isolation": "fresh"
  }
}
```

Task default:

```json theme={null}
{
  "title": "Run migration tests",
  "description": "Apply the migration on a clean workspace and report failures.",
  "assignTo": "qa-agent",
  "sandbox": {
    "isolation": "fresh"
  }
}
```

One chat request:

```json theme={null}
{
  "agent": "qa-agent",
  "messages": [{"role": "user", "content": "Run the test suite"}],
  "sandbox": {
    "isolation": "fresh"
  }
}
```

## Storage and state

Fresh isolation controls the execution sandbox, not project storage. Project
files, memory, Connections, task state, and session history follow their normal
project-scoped persistence rules.

On Polpo Cloud, `reuse` uses the managed project sandbox pool and `fresh`
bypasses idle reuse for that run. Self-hosted runtimes carry the same policy in
the runtime contract; the host sandbox adapter decides how to materialize it.