Volumes

A volume is named storage. Create it once, mount it wherever you need it, and it stays alive regardless of what gets deployed or deleted around it.

data = cycls.Volume("training-data")


@cycls.function(volumes={"/data": data})
def crunch(day):
    import pandas as pd
    return pd.read_parquet(f"/data/events-{day}.parquet").sum()

Inside the container, /data is the volume. Files written there survive calls, instances and redeploys, and any other deployment mounting training-data sees the same files.

The mental model

A volume is shared files, not a database. Reads and writes are ordinary filesystem operations, which has two consequences worth knowing up front:

Concurrent writes to the same file are last write wins. There is no locking. Give concurrent writers distinct paths, such as one file per user or per run, and the problem disappears.
A file written by one deployment becomes visible to others within seconds, not instantly.

Creating and attaching

Referencing a volume creates it. The first deploy that mentions training-data brings it into existence and says so in the deploy output, so a typo shows up as a new volume rather than a silent empty one. To be explicit first:

cycls volume create training-data

volumes= maps mount paths to volumes on any decorator:

state = cycls.Volume("staging-state")
prod = cycls.Volume("app-data")


@cycls.app(name="staging", volumes={
    "/workspace": state,
    "/prod": prod.read_only(),                # visible, not writable
    "/users": prod.sub_path("users/123"),     # one subtree only
})
def staging(port): ...

Modifier	Effect
`.read_only()`	mount without write access
`.sub_path("a/b")`	mount only that subdirectory

The workspace convention

/workspace is where apps and agents keep state: chats, per-user files, credentials and the key-value store. Agents require a volume there and the decorator raises without one. Apps need one only if they use workspace or DB.

@cycls.agent(volumes={"/workspace": cycls.Volume("my-agent")})
async def my_agent(context): ...

Nothing is created implicitly. Storage is exactly what your source declares, and renaming a deployment changes nothing about its data, because the volume reference is the identity.

cycls run ignores volumes. Locally your code sees the local filesystem, which keeps the development loop fast and offline.

Moving data in and out

The CLI talks to storage directly, so transfers do not proxy through the API and file size is effectively unlimited.

cycls volume put training-data ./model.bin models/model.bin
cycls volume get training-data outputs/result.parquet .
cycls volume ls training-data              # contents
cycls volume ls training-data models/      # contents under a prefix
cycls volume rm training-data models/old.bin
cycls volume ls                            # every volume, with attachments

This is how you seed a dataset before anything is deployed, and how you pull results out without writing an endpoint. Attachment is by name, so a family of deployments can work on one dataset.

shared = cycls.Volume("pipeline")

@cycls.function(volumes={"/pipe": shared})
def extract(day): ...        # writes /pipe/raw/<day>.json

@cycls.function(volumes={"/pipe": shared})
def transform(day): ...      # reads raw/, writes clean/

@cycls.app(name="dashboard", volumes={"/pipe": shared.read_only()})
def dashboard(port): ...     # serves clean/, cannot corrupt it

One volume, three deployments, no copying. Put a schedule on the producer and the pipeline runs itself. For a worked version of this with Parquet and DuckDB, see Build a data warehouse.

Lifecycle

cycls rm <deployment> detaches volumes and leaves the data alone. Redeploying the same name reattaches them with files intact.
cycls volume delete <name> is the only way to delete data. It refuses while any deployment has the volume attached, and names them in the error.
Deleted volumes stay recoverable for seven days.

Structured state on a volume

For per-user JSON rather than files, cycls.DB is a small key-value store that writes to the workspace volume.

db = cycls.DB(context.workspace)

await db.put("usage/2026-09", {"count": 12})
entry = await db.get("usage/2026-09", {"count": 0})
async for key, value in db.items(prefix="usage/"):
    ...
await db.delete("usage/2026-08")

Method	Meaning
`await db.get(key, default=None)`	read one key
`await db.put(key, value)`	write one key, atomic per key
`await db.delete(key)`	remove a key, trailing slash clears a namespace
`db.items(prefix=, glob=, limit=)`	async iterator of key and value
`db.keys(prefix=)`	keys only
`db.scan(prefix=)`	one round trip listing

Cron

Fire a deployed function on a schedule.

Get started

Functions

Apps

Agents

Interface and users

Ship it

Guides

Reference

Resources

For LLMs

The mental model

Creating and attaching

The workspace convention

Moving data in and out

Lifecycle

Structured state on a volume

Next

Cron

​The mental model

​Creating and attaching

​The workspace convention

​Moving data in and out

​Sharing across deployments

​Lifecycle

​Structured state on a volume

​Next

Cron

The mental model

Creating and attaching

The workspace convention

Moving data in and out

Sharing across deployments

Lifecycle

Structured state on a volume

Next