Sessions

What is a session?

A session is a persistent /workspace filesystem — not a held GPU. All commands within a session share the same filesystem, environment, and installed packages. It's cold ($0, no host) until used, comes online automatically when you target it, and keeps its files across stops and host changes.

The core workflow

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

State persists across commands: the pip install is still there for the python train.py that follows. Address an existing session with --on <sid> or a bare positional s-... argument.

Without --on, exec and run create a throwaway session, do the work, and release it automatically — its filesystem is still saved and downloadable afterwards.

Session lifecycle

A session moves between these states, reported by fcloud sessions:

A new session starts cold and costs nothing until its first command. When you run something against a cold session, fcloud transparently brings it back online — there is no explicit resume step, even hours or days later, even after the original host is long gone: the session is rebuilt on a fresh host with /workspace restored from cloud storage. fcloud stop (or s.close() from the SDK) halts spend immediately; idle sessions also stop on their own.

fcloud sessions              # active sessions
fcloud sessions --all        # include cold/closed
fcloud history s-abc123      # lifecycle timeline for one session
fcloud stop s-abc123 --wait  # stop and block until the file manifest is durable

Preemption

Sessions run on spot capacity. When a host is reclaimed, fcloud by default checkpoints the live sandbox (GPU state included) and restores it on a fresh host, pinned to the region the checkpoint lives in — running processes continue, but the restore may wait for capacity in that region. Turn it off per session with --no-checkpoint (SDK checkpoint=False), or by default with fcloud config set checkpoint off: the session is then rebuilt cold on any available host — /workspace is kept, running processes are lost.

What survives a resume

/workspace always survives. Changes outside it (e.g. pip install into the image's site-packages) survive an ordinary resume but are reset when the image spec changes. For packages that must survive unconditionally, install into a venv under the workspace — or better, put them in the image spec so every resume rebuilds from the content-addressed cache (see Projects & config).

Background processes

Start long-running work without blocking, then follow it by process id:

fcloud spawn --on s-abc123 python train.py --epochs=100   # prints proc-456
fcloud logs s-abc123 proc-456 --follow
fcloud wait s-abc123 proc-456        # blocks; exits with the process's exit code
fcloud kill s-abc123 proc-456

The SDK mirrors this:

s = project.session(sku="gpu_1x_a10g")
proc = s.spawn(["python", "train.py", "--epochs=100"])
proc.poll()        # check status
print(proc.output) # read output
proc.wait()        # block until done
s.close()

Sessions vs. jobs

A session saves its filesystem; a job (fcloud job run) doesn't — it runs one command to completion and keeps only its exit code, logs, and volume writes, in exchange for skipping storage sync. Use a session when you'll iterate or want the files later; use a job for batch runs with declared outputs. See Batch: jobs & sweeps.