Quickstart

Installation

curl -fsSL https://fcloud-home.vercel.app/install.sh | sh

One chain: installs the fcloud CLI and Python SDK (from PyPI, into an isolated tool environment via uv or pipx), adds it to your shell's PATH, opens your browser to sign in with Google or email and add a card, hands the CLI its own API key, and installs the fcloud skill for any coding agents on your machine (Claude Code, Cursor, Codex).

Re-running it is safe: an existing install is upgraded in place (or left alone if something other than uv/pipx installed it), and the sign-in is skipped when this machine already has a key. Knobs:

The installer runs in its own process, so it cannot change the PATH of the terminal you ran it in. It writes the line to your shell profile for every new terminal and prints the one command that makes the current one catch up (export PATH="$HOME/.local/bin:$PATH", or source ~/.zshrc).

Manual install

Prefer to manage Python yourself? The CLI is the fcloud-sdk package on PyPI (Python 3.10+). Any of these work:

uv tool install fcloud-sdk        # isolated tool env, on PATH at ~/.local/bin
pipx install fcloud-sdk           # same idea, via pipx
pip install fcloud-sdk            # into the current Python environment

Then sign in — it opens your browser, and the CLI receives its own key:

fcloud login

If fcloud is not found afterwards, the tool's bin directory is not on your PATH yet. For uv and pipx that is ~/.local/bin:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc   # or ~/.bashrc
source ~/.zshrc

To teach your coding agent about fcloud (Claude Code, Cursor, Codex):

fcloud setup --agents all

Authentication

fcloud login signs in through your browser: it shows a short code, opens the approval page, and saves a key minted for this machine (named cli:<hostname> in the dashboard, so one laptop can be revoked without the others). On a headless box it prints the URL and code to open from any device. Already have a key — CI, agents, a second machine?

fcloud set_token fcloud_sk_...
fcloud setup --agents all     # optional: install agent skills for every agent

Verify connectivity:

fcloud health

Add credit

fcloud is prepaid: GPUs draw down a credit balance as they run, and at $0 new work is refused. Buy your first credit before the first run — this is also what turns auto-refill on, so you are not interrupted later.

fcloud credits buy 25      # opens a checkout page in your browser
fcloud credits             # balance, available, auto-refill, card

available is the number to watch: it is your balance minus usage that has been metered but not yet billed. See Credits for auto-refill and statements.

Pick a GPU SKU

GPUs are selected by SKU name (for example gpu_1x_a10g or gpu_8x_b200). List everything available with:

fcloud skus

Or find your SKU in the browser — filter by GPU count and compare memory.

Run your first command

fcloud exec nvidia-smi

Target a specific SKU:

Run a script

fcloud run uploads a file (or a directory) and runs it — no session bookkeeping required:

fcloud run train.py --sku gpu_1x_l4

# Upload a whole directory, pick the entrypoint, pass arguments
fcloud run . --script train.py --sku gpu_1x_l4 -- --epochs 50 --lr 1e-4

Iterate on one machine

For multi-step work, create a persistent session once and attach every command to it with --on. The session is cold — $0 — until first used, and its /workspace filesystem persists across commands:

fcloud create --sku gpu_1x_l4              # prints s-abc123; $0 so far
fcloud upload s-abc123 ./data
fcloud exec --on s-abc123 pip install torch
fcloud exec --on s-abc123 python train.py  # brings the host online
fcloud stop s-abc123                       # spend stops, files stay
fcloud download s-abc123 model.pt          # works after it's stopped

There is no resume command — using a stopped session again brings it back online automatically with its files restored, even days later.

Kick off something long

Don't babysit a training run in the foreground. spawn starts it in the background and prints a process id you can follow — the logs are durable, so this works even if your laptop sleeps or the job outlives your terminal:

fcloud spawn --on s-abc123 python train.py --epochs 100   # prints proc-456
fcloud logs s-abc123 proc-456 --follow                    # watch it live
fcloud wait s-abc123 proc-456                             # block; exits with its exit code

Keep data that outlives any session

Sessions keep their own files, but a volume is how you share data across sessions — checkpoints written on a training box, read on an eval box, or pulled straight to your laptop with no session running at all:

fcloud volume create checkpoints

# Train on one session, writing into the mounted volume
fcloud exec --sku gpu_1x_l4 --volume checkpoints:/workspace/ckpt \
  -- sh -lc 'python train.py && cp model.pt /workspace/ckpt/'

# Writes commit when the session closes — then any session can mount them
fcloud volume files checkpoints                # -> model.pt
fcloud exec --sku gpu_1x_h100 --volume checkpoints:/workspace/ckpt \
  python eval.py --model /workspace/ckpt/model.pt

# Or pull results locally, no GPU involved
fcloud volume download checkpoints model.pt

Inside the session a volume is just a directory — use normal file I/O. See Volumes for commit semantics and volume import.

Fan out

When one run becomes a grid, fcloud map runs the same command across many argument bindings as a durable server-side sweep — submit, disconnect, and the service queues, retries, and records every task:

fcloud map --name lr-sweep --sku gpu_1x_l4 \
  -- python train.py --lr {lr} ::: lr=1e-4,3e-4,1e-3

fcloud sweep status lr-sweep                  # progress + failures by error
fcloud sweep harvest lr-sweep '*.json' ./out  # every task's outputs

See Batch: jobs & sweeps for binding syntax, canaries, and run-to-completion jobs.

Scripting and agents: --json

Every command accepts --json for machine-readable output:

fcloud exec --sku gpu_1x_l4 --json nvidia-smi -L
# {"stdout": "GPU 0: NVIDIA L4 ...\n", "returncode": 0, "status": "exited", ...}

Use the Python SDK

The same primitives are available programmatically:

import fcloud

client = fcloud.Client()
project = client.project("my-experiment")

with project.session(sku="gpu_1x_l4") as s:
    s.run(["pip", "install", "transformers"])
    result = s.run(["python", "train.py"])
    print(result.stdout)

Next steps

• CLI Reference — every command, grouped by task
• Credits — balance, auto-refill, what happens at $0
• Sessions — lifecycle, what survives a resume
• Volumes — commit semantics, imports, config defaults
• Batch: jobs & sweeps — jobs, ::: bindings, harvest
• Python SDK Guide — deep dive into the SDK