Volumes

Volumes are named, manifest-backed folders for moving data between sessions — checkpoints from a training session into an eval session, a job's outputs back to your laptop. They are not EBS volumes and reserve no block storage: file bytes live in the shared content-addressed blob store, and the volume records the path → blob manifest.

Commands

Reads need no session and no host — files/download/cat serve the committed manifest straight from the API, which is how you get a job's outputs back.

Mounting into a session

Attach with repeatable --volume flags on exec, run, shell, spawn, job run, and map:

fcloud exec --volume checkpoints:/workspace/ckpt --sku gpu_1x_l4 python train.py

--volume NAME mounts at /workspace/NAME; --volume NAME:/absolute/path mounts at that path. Inside the session a volume is just an ordinary directory — use normal file I/O. Writes land in a writable overlay and are committed back as a new volume version when the session detaches or closes (the commit can trail close by ~30s).

A volume attaches to at most one session at a time; browsing, import, and delete return a conflict while it's attached. Mount onto an empty path — attaching over existing session files is rejected rather than silently shadowing them.

Volumes are not block devices: there's no /dev/* node, and mount/lsblk/ df inside the session won't show them. Don't try to mount, unmount, or format anything — just read and write files.

End-to-end: carry results across sessions

# 1. Create the volume once.
fcloud volume create runs

# 2. Run something that writes into the mounted volume.
fcloud exec --volume runs:/workspace/runs --sku gpu_1x_l4 \
  -- sh -lc 'python train.py && cp model.pt /workspace/runs/model.pt'

# 3. After the session closes, the file is committed to the volume.
fcloud volume files runs            # -> model.pt

# 4. A later session mounts the same volume and sees the file.
fcloud exec --volume runs:/workspace/runs --sku gpu_1x_l4 \
  -- ls -l /workspace/runs/model.pt

# 5. Or pull it back locally, no session needed.
fcloud volume download runs model.pt

Importing from a session

volume import copies a folder from a stopped session's finalized manifest into a volume — a single batch metadata operation that copies no bytes for blobs that already exist:

fcloud stop s-abc123 --wait
fcloud volume import checkpoints s-abc123 runs/run-42 run-42
fcloud volume files checkpoints run-42

Defaults in fcloud.json

Declare volumes once to skip --volume on every command:

{ "sku": "gpu_1x_l4", "volumes": [{ "name": "checkpoints", "mount": "/workspace/checkpoints" }] }

The effective set is the config volumes plus any --volume flags, keyed by name; a --volume for a name already in the config re-maps its mount path for that invocation. Attach is idempotent — re-passing an already-mounted volume is a safe no-op, including across stop/resume on a fresh host.