> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polpo.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Storage

> Persistent project files and Cloud volume metadata

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.

<Warning>
  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.
</Warning>

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`:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```bash theme={null}
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](/docs/platform/self-hosting) for supported file, SQLite, and PostgreSQL runtime storage.

See the [Agent API overview](/agent-api/overview) and its generated **Files** operations for endpoint schemas.