Storage

Every sandbox gets a writable local workspace at /home/daytona/project/workspace. You do not need to create or configure a volume to use file, shell, browser, or code tools. Local workspace data follows the sandbox lifecycle. Create a persistent volume only when files must survive independently of one sandbox or be shared with the Files API.

Persistent volumes

Volumes are project resources backed by project-scoped object storage. A volume has one canonical strategy:

Strategy	Behavior	Best for
`mounted`	Mounts persistent storage live at the configured sandbox path. Writes are immediately persistent.	Shared files, datasets, and direct file access.
`hydrated`	Copies persistent files to local sandbox disk before the run.	Builds and tools that need local filesystem semantics or higher I/O throughput.

Both strategies support read-only and read-write access. A read-write hydrated volume also requires a writeback policy:

auto synchronizes changed files before the outer run releases its sandbox.
manual requires the agent to call sandbox_volume_checkpoint after a consistent set of changes. A dirty manual volume fails finalization instead of silently dropping changes.

Read-only hydrated volumes are verified at finalization. A run that modifies one fails instead of persisting or discarding the change silently.

Agent grants

Creating a volume does not expose it to every agent. Grant each agent only the volumes it needs in Agent > Security. A grant can narrow the volume to read-only or manual writeback, but cannot widen the project volume policy. At runtime, callers may narrow the granted set again:

{
  "sandbox": {
    "volumes": [
      {
        "name": "reference",
        "access": "read-only"
      }
    ]
  }
}

The request receives only the selected volume. It cannot add an ungranted volume, change its host-owned mount path, or widen its access. Catalog configuration, authorization, and runtime selection are intentionally separate. An agent’s sandbox.volumes field only selects or narrows existing grants; it does not create a volume or grant access during polpo deploy.

Volume CLI

Manage the project catalog from any linked project directory:

polpo volumes list
polpo volumes get reference

polpo volumes create reference \
  --strategy hydrated \
  --access read-only \
  --mount-path /home/daytona/project/reference

polpo volumes update reference --label "Reference files"
polpo volumes remove reference --yes

Create, inspect, narrow, or revoke per-agent grants by stable volume name:

polpo volumes grants list --agent researcher
polpo volumes grants set reference --agent researcher --access read-only
polpo volumes grants revoke reference --agent researcher --yes

Add --json to every command for machine-readable output. Destructive commands require interactive confirmation or --yes in automation. The CLI resolves a volume name to its immutable id before modifying a grant and fails if the name is absent.

Volume API

List and create project volumes:

curl "$POLPO_URL/v1/files/volumes" \
  -H "Authorization: Bearer $POLPO_API_KEY"

curl -X POST "$POLPO_URL/v1/files/volumes" \
  -H "Authorization: Bearer $POLPO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "reference",
    "label": "Reference files",
    "strategy": "hydrated",
    "access": "read-only",
    "mountPath": "/home/daytona/project/reference"
  }'

Update or delete one volume with PATCH or DELETE on /v1/files/volumes/{name}. Volume names are stable and cannot be renamed. They must start with a lowercase letter, contain only lowercase letters, digits, dashes, or underscores, and contain 2 to 63 characters. Mount paths must stay below /home/daytona/project, cannot overlap, and cannot cover the reserved .polpo tree. The runtime also rejects paths that resolve through symlinks before mounting or hydrating storage. Grant and revoke agent access with:

GET    /v1/files/volume-grants/{agentName}
PUT    /v1/files/volume-grants/{agentName}/{volumeId}
DELETE /v1/files/volume-grants/{agentName}/{volumeId}

Provider credentials, storage prefixes, revisions, and synchronization state are host-owned. They are never accepted from a public create or update payload.

Files SDK

The SDK exposes project file methods directly on PolpoClient:

const { roots } = await client.getFileRoots();
const { entries } = await client.listFiles("reference/docs");
const preview = await client.previewFile("reference/docs/guide.md", 200);

const response = await client.readFile("reference/docs/guide.md");
const source = await response.text();

Upload a File or Blob to a persistent volume path:

const file = new Blob(["enabled=true\n"], { type: "text/plain" });
await client.uploadFile("reference/config", file, "app.env.example");

Other operations are also direct client methods:

await client.createDirectory("reference/src/components");
await client.renameFile("reference/src/old.ts", "new.ts");
await client.deleteFile("reference/src/unused.ts");
const matches = await client.searchFiles("config", "reference", 20);

The TypeScript SDK also exposes the managed volume catalog and grant contract:

const catalog = await client.listSandboxVolumes();
const volume = await client.createSandboxVolume({
  name: "build_cache",
  strategy: "hydrated",
  access: "read-write",
  writeBack: "auto",
});

await client.setSandboxVolumeGrant("builder", volume.id, {
  access: "read-write",
  writeBack: "manual",
});

Concurrency and failure behavior

Hydrated writeback uses revision compare-and-swap. If two runs hydrate the same revision, only the first valid writeback can commit. The other run fails with a conflict rather than overwriting newer data. Sandbox pooling also includes the resolved volume-plan fingerprint. A pooled sandbox is reused only when its mounted paths, policies, and storage selection match the new run.

Self-hosted providers

The volume contract is provider-neutral in Polpo OSS. A self-hosted sandbox provider decides how to implement mounted, hydration, checkpoint, writeback, and finalization. Polpo Cloud supplies the managed object-storage adapter. See Sandboxes for isolation and lifecycle policy.

Getting Started

Platform

Agents

Orchestration

Persistent volumes

Agent grants

Volume CLI

Volume API

Files SDK

Concurrency and failure behavior

Self-hosted providers

​Persistent volumes

​Agent grants

​Volume CLI

​Volume API

​Files SDK

​Concurrency and failure behavior

​Self-hosted providers

Persistent volumes

Agent grants

Volume CLI

Volume API

Files SDK

Concurrency and failure behavior

Self-hosted providers