Projects & Config
Organize workloads and set per-project defaults.
Project config (fcloud.json)
For CLI workflows, a project is a directory with an fcloud.json in its root.
The CLI auto-discovers it by walking up from your current directory (like
.env), and every fcloud exec/run in that tree picks up its defaults:
{
"sku": "gpu_1x_l4",
"volumes": [{ "name": "checkpoints", "mount": "/workspace/checkpoints" }],
"image": {
"base": "nvidia/cuda:12.8.1-devel-ubuntu24.04",
"apt": ["git", "build-essential", "ninja-build"],
"pip": ["torch", "triton", "transformers"],
"env": { "PYTHONUNBUFFERED": "1" },
"run": ["echo setup-complete"]
}
}All fields are optional. Explicit --sku flags override the file; --volume
flags merge with (and re-map by name) the volumes defaults.
| Field | Description |
|---|---|
sku | Default hardware SKU for exec and run |
volumes | Volumes auto-attached to every session. Each entry is "name", "name:/mount", or {"name": ..., "mount": ...} |
image.base | Base image (default: python:3.11-slim) |
image.apt | Packages to apt-get install |
image.pip | Packages to pip install |
image.env | Environment variables baked into the image |
image.run | Shell commands to run during build |
When fcloud.json is present, fcloud exec and fcloud run automatically
build the specified image. Images are cached by content hash — same config,
instant startup; a changed config triggers one rebuild (30–120s) on first run.
Projects in the SDK
In the Python SDK, a project is a logical grouping of sessions with a shared image definition — one per experiment, team, or environment. Projects are created implicitly when first referenced:
import fcloud
from fcloud import Image
client = fcloud.Client()
image = Image.debian_slim().pip_install(["torch", "transformers"])
project = client.project("fine-tuning-llama", image=image)
s = project.session(sku="gpu_1x_a10g")
s.run(["python", "train.py"])
s.close()For quick scratch work, use a throwaway name like _scratch.