Volumes and cloud buckets

A volume is declared in Python and attached to each workload that needs it. LazyCloud creates it on first mount and reuses it after that.

Declare and use a volume

Save this as reports.py:

import json
from pathlib import Path

from lazycloud import App, Volume

app = App("reports")
reports = Volume("sales-reports", "/reports")


@app.function(volumes=[reports])
def save_report(amounts_cents: list[int]) -> dict[str, int]:
    summary = {"sales": len(amounts_cents), "total_cents": sum(amounts_cents)}
    Path("/reports/latest.json").write_text(json.dumps(summary))
    return summary


if __name__ == "__main__":
    print(save_report.remote([1200, 3500, 800]))
    reports.get("latest.json", "latest.json")

Run it:

uv run python reports.py

The cloud function writes the report, and the script downloads it to your current directory. Within a workspace a volume name always means the same files, even from another app. A new name is a new, empty volume, and removing a mount or a deployment never deletes stored files. Volumes live with their workspace and bill per GiB-month.

Upload inputs before the first run

A local setup script can seed a volume before any workload runs:

from lazycloud import Volume

models = Volume("models", "/models")
models.create()
models.put("weights.pt", "weights.pt")

A function with volumes=[models] then reads /models/weights.pt. create() reuses an existing volume. Setup like this belongs behind if __name__ == "__main__":, so importing the module never uploads anything.

Read and write from Python

Inside a container a volume is a directory. Locally, the Volume object reads and writes it:

from reports import reports

print(reports.read_text("latest.json"))
print(reports.list())
print(reports.stat("latest.json"))
reports.get("latest.json", "downloaded-report.json")

put(), write_text(), write_bytes(), read_bytes(), list_path(), and move() cover the rest. Multi-gigabyte uploads go in parts through create_multipart_upload() and its companions. Every container that mounts a volume sees the same files. Under the directory is object storage, which sets a few rules:

A file appears to other containers, and becomes durable, when its writer closes it.
Two writers to one path don’t merge. The last close wins, so each call writes its own path, such as /reports/{task_id}.json.
There are no locks. A queue or map coordinates turns.
Appending to a large file rewrites it, so logs fit better as many small files.

Weights downloaded once serve every container:

from pathlib import Path

from lazycloud import App, GpuType, Volume

app = App("inference")
models = Volume("models", "/models")
WEIGHTS = Path("/models/encoder.safetensors")


def ensure_weights(context: object) -> None:
    if WEIGHTS.exists():
        return
    partial = WEIGHTS.with_suffix(".part")
    download_weights(partial)   # your download code
    partial.rename(WEIGHTS)


@app.function(gpu=GpuType.L4, volumes=[models], on_start=ensure_weights, concurrency=4, in_process=True)
def encode(text: str) -> list[float]:
    ...

Writing to .part and renaming means no container ever sees a half-written file. Two containers starting together may both download, which wastes one download but corrupts nothing.

Mount an existing cloud bucket

CloudBucket mounts an S3-compatible bucket you own, reading and writing it in place.

from pathlib import Path

from lazycloud import App, CloudBucket, CloudBucketConfig

app = App("etl")
bucket = CloudBucket(
    "my-data-bucket",
    "/data",
    CloudBucketConfig(
        access_key="MY_BUCKET_ACCESS_KEY",
        secret_key="MY_BUCKET_SECRET_KEY",
        region="us-east-1",
    ),
)


@app.function(volumes=[bucket])
def read_text_file(key: str) -> str:
    return (Path("/data") / key).read_text()

access_key and secret_key name secrets; both are required. bucket, prefix, endpoint, force_path_style, and read_only cover other layouts and stores. Requests name the bucket in the host name, as AWS expects; stores such as MinIO that take the bucket in the path need force_path_style=True. A bucket name with a dot always goes in the path. The bucket must already exist. The video highlights example reads its input this way.

Memory for mounts

A container runs one mounter for all its volumes, plus one per distinct cloud bucket. Cloud buckets that differ only in prefix share one. Each mounter reserves 768 MiB of memory on top of the container’s memory, billed as memory, so a function with two volumes and one cloud bucket reserves 1.5 GiB beyond what it asks for.

Delete stored data

reports.remove("latest.json") deletes one file and reports.delete() the whole volume. delete() fails while a container that hasn’t stopped mounts the volume. A workload that still declares the volume creates it empty on its next run. The file commands work from a terminal too.

Getting started

Core concepts

CLI reference

Examples

Account

Volumes and cloud buckets

Declare and use a volume

Upload inputs before the first run

Read and write from Python

Mount an existing cloud bucket

Memory for mounts

Delete stored data

Declare and use a volume

Upload inputs before the first run

Read and write from Python

Share files between containers

Mount an existing cloud bucket

Memory for mounts

Delete stored data