Storage

Polpo Cloud stores project files in project-scoped S3-compatible object storage. The Files API, dashboard, built-in file tools, custom tools, and Cloud sandboxes use the same project prefix. When a sandbox needs project files, Cloud exposes that object storage through an S3/FUSE-backed mount. The default logical root is workspace, mounted at /home/daytona/project/workspace in the managed execution environment.

Volumes

Volume records define logical roots and their mount metadata. A project has a default workspace volume.

Field	Description
`name`	Stable root identifier
`label`	Display name
`mode`	`file-drive` or `code-drive`
`mountPath`	Managed sandbox path
`storage`	Optional storage metadata
`sync`	Optional sync metadata and ignore configuration

The current Cloud file system uses the same R2/S3 backend and s3-fuse runtime backend for both modes. file-drive is the default. code-drive currently records workload intent and changes the dashboard icon; it does not switch to a separate implemented hydrate-and-sync engine.

Do not rely on code-drive to copy files to an independent local disk and sync them back after execution. The active runtime path mounts the project object store instead.

The stored default ignore list for sync metadata is:

node_modules
.git
.next
dist
build
.turbo
coverage

Those values are metadata for sync-aware consumers; they do not alter normal Files API reads and writes.

Files SDK

The SDK exposes file methods directly on PolpoClient:

const { roots } = await client.getFileRoots();
const { entries } = await client.listFiles("workspace/src");
const preview = await client.previewFile("workspace/src/index.ts", 200);

const response = await client.readFile("workspace/src/index.ts");
const source = await response.text();

Upload a File or Blob to a destination directory:

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

Other operations are also direct client methods:

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

There is no client.files namespace in the current SDK.

Files API

Cloud data-plane routes use the project endpoint and Bearer authentication:

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

curl "$POLPO_URL/v1/files/list?path=workspace/src" \
  -H "Authorization: Bearer $POLPO_API_KEY"

Volume metadata is available at /v1/files/volumes, with POST for creation and PATCH or DELETE on /v1/files/volumes/{name}. Volume names must start with a lowercase letter, contain only lowercase letters, digits, dashes, or underscores, and be between 2 and 63 characters.

Lifecycle

Project creation provisions the storage prefix and default workspace metadata.
File writes through the API and tools update the same object-storage prefix seen by mounted Cloud sandboxes.
Deleting a project blocks access immediately; project storage is purged by the deferred project cleanup process.

Self-hosted files

The open-source server uses its configured project directory and storage stores. It does not expose Cloud R2 volume provisioning or a pluggable DriveFS adapter contract. See Self-hosting for supported file, SQLite, and PostgreSQL runtime storage. See the Agent API overview and its generated Files operations for endpoint schemas.

Getting Started

Platform

Agents

Orchestration

Volumes

Files SDK

Files API

Lifecycle

Self-hosted files

​Volumes

​Files SDK

​Files API

​Lifecycle

​Self-hosted files

Volumes

Files SDK

Files API

Lifecycle

Self-hosted files