Volumes

Named persistent storage you attach to any deployment at any mount path. Data outlives the deployments that use it.

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.

Sharing across deployments

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

Next

Cron

Fire a deployed function on a schedule.