Sandboxes

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.

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

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

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

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

Override one chat request

{
  "agent": "qa-agent",
  "messages": [
    { "role": "user", "content": "Run the test suite" }
  ],
  "sandbox": {
    "isolation": "fresh",
    "lifecycle": {
      "onRelease": "pool",
      "stopAfterIdleMinutes": 30,
      "deleteAfterStopMinutes": 60
    }
  }
}

Configure a task

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

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.

Getting Started

Platform

Agents

Orchestration

Isolation

Lifecycle

Common policies

Precedence

Persistent volumes

Configure an agent

Override one chat request

Configure a task

Observe sandbox activity

Files and persistent state

​Isolation

​Lifecycle

​Common policies

​Precedence

​Persistent volumes

​Configure an agent

​Override one chat request

​Configure a task

​Observe sandbox activity

​Files and persistent state

Isolation

Lifecycle

Common policies

Precedence

Persistent volumes

Configure an agent

Override one chat request

Configure a task

Observe sandbox activity

Files and persistent state