Workspaces
A workspace is one running pod with your source tree, a Nix profile of the packages you asked for, and ssh. One workspace per change you are making; they are cheap to create, clone, and delete.
A workspace is one running pod with your source tree, a Nix profile of the packages you asked for, and ssh. One workspace per change you are making; they are cheap to create, clone, and delete.
What is in a workspace
| Path | What | Persists |
|---|---|---|
/home/kl | The workspace's own btrfs volume, sized by quota_gb; this workspace's home, not shared with any other | Across stop and start; snapshotted by push; replicated |
/home/kl/workspace | Your source tree | With the home: a clone or a restore arrives warm |
Caches under /home/kl | Every cache at its tool's own default (./target, ~/.cargo, ~/.rustup, ~/go, ~/.cache): build output, package stores, toolchains, browsers, editor servers | With the home: a clone or a restore arrives warm |
PATH | The packages in packages, plus a base set | Rebuilt from the spec on every start |
The standard: a workspace carries its caches. Everything a tool would cache — build output, downloaded packages, toolchains, editor servers — lives under .cache/ inside the home volume, so it is snapshotted by push, replicated on the sync beat, and present the moment a clone or a restore comes up. A clone or restore carries the whole home, credentials included; it is always your own workspace, never shared with another. Nothing rebuildable is left behind on a node.
What the platform places inside the tree — .cache/, .direnv/ — is ignored by git through ~/.config/git/ignore, never through a repository's own .gitignore.
Image
Default image is ghcr.io/kloudlite/kloudlite-workspace, which carries the ssh server, Nix, and the kl CLI. A custom image may replace it; it then owns its own ssh setup and mounts no authorized_keys.
Packages
packages is a list of nixpkgs attribute names. Bare nodejs means the region's nixpkgs pin; nodejs@22 is locked to the newest 22.x that the binary cache holds, and the lock is frozen into the workspace before it is created. See Packages.
State
creating ─▶ ready ⇄ stopped ─▶ deleted │ ▼ error| State | Meaning |
|---|---|
creating | Placed and being built; packages_status and ssh fill in as they arrive |
ready | The pod is running and accepting ssh |
stopped | The pod is gone; the tree is kept and a sync point was cut |
error | The controller could not converge; degraded says why |
deleted | Being torn down; the volume survives only if a snapshot references it |
Placement
A workspace is placed on one node in its region. Its tree is replicated to other nodes on a sync beat, so a stopped workspace may start on any node that already holds its newest sync point. A running one is never moved; if its node dies it is interrupted, and the way forward is a clone from the last synced point.
Seeding from a repository
repo and branch on create run a clone inside the pod with your platform ssh key, into /home/kl/workspace. No credential is minted or stored for it.