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. For typed application records, use Databases. Databases and Volumes are separate project resources with their own access grants.

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