Runtime Sandboxes

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

{
  "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:

project/runtime settings
agent configuration
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:

{
  "name": "qa-agent",
  "allowedTools": ["read", "write", "bash"],
  "sandbox": {
    "isolation": "fresh"
  }
}

Task default:

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

One chat request:

{
  "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.

Getting Started

Platform

Agents

Orchestration

Runtime Sandboxes

Precedence

Where to set it

Storage and state

​Precedence

​Where to set it

​Storage and state

Precedence

Where to set it

Storage and state