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

# Filesystems

> Mount durable file storage into a Capsule runtime.

Filesystems give your app durable mounted storage inside the sandboxed runtime.

Each app user runs in an isolated runtime, and your code can work with normal container-local paths plus any filesystems declared on the app. Use mounted filesystems for uploaded documents, generated reports, exports, cached model artifacts, and large intermediate outputs that should outlive one request.

## Create a filesystem

```bash theme={null}
capsule fs create reports
```

## Mount it

```python theme={null}
app = cpsl.App(
    name="reports",
    image=cpsl.Image(),
    filesystems={"/data": cpsl.FileSystem("reports")},
)
```

Inside the runtime, `/data` behaves like a normal directory. Your handlers, tasks, schedules, and workflows can all read and write through that path.

The mount is an app/workspace resource, not a private directory automatically created per end user. If files are user-specific, namespace paths yourself, for example `/data/users/{session.user.id}/summary.md`, or keep private/queryable state in user-scoped collections and store only generated artifacts in the filesystem.

## Write files

```python theme={null}
@app.task()
async def write_report():
    with open("/data/summary.txt", "w") as f:
        f.write("Generated by Capsule\n")
```

## Accept uploads

```python theme={null}
@app.message()
async def handle(session: cpsl.Session, msg: cpsl.Message):
    upload = await session.prompt_file(
        message="Upload a CSV",
        accept=".csv,text/csv",
        path="/data/uploads",
    )
    await session.reply(f"Uploaded {upload.name} to {upload.path}")
```

## Manage files with the CLI

```bash theme={null}
capsule fs ls reports /
capsule fs upload reports ./report.csv /incoming/report.csv
capsule fs download reports /incoming/report.csv ./report.csv
```

## Filesystems versus collections

Use [collections](/features/collections) for queryable records. Use filesystems for files and artifacts.

Many apps use both: a collection row stores metadata and points at a file in a mounted filesystem.

## Related

* [Connect Services](/build/connect-services)
* [Image, Theme, And Deployment Reference](/reference/image-theme-and-deployment)
* [CLI Reference](/reference/cli)