Execution nodes

Experiments don't run on the control node — they run on execution nodes (runners): machines you attach. A node clones the project's private code and runs scheduled experiments in an isolated git worktree per run. Connect whatever compute you have; nodes are heterogeneous by design.

Nothing runs until a node is attached

A live project with no execution node will queue experiments but never run them. Attaching a node is what turns idle compute into results.

Turn this machine into a node

autolab serve --project alice/nanochat

The host registers as a node and starts polling for work. Because it fetches private code, registration needs a researcher+ token (researcher, admin, or owner). The token is read from, in order: --token, then AUTOLAB_TOKEN, then your stored autolab login.

serve options

Option	Default	Meaning
--project	(required)	Project slug owner/slug to run jobs for.
--name	hostname	Node name shown in the dashboard.
--poll-interval	5	Seconds between polls for new work.
--token	—	Researcher+ token to register with.
--autolab-home	~/.autolab	Root dir for node workspaces.

Node workspaces live under <AUTOLAB_HOME>/<hostname>/projects/<owner>--<slug>/. The hostname namespacing makes a shared NFS root collision-safe.

Headless / remote GPU box

An agent (or you) can bootstrap a remote node over SSH with a dedicated, revocable token — no browser on the remote box:

TOK=$(autolab token create --name gpu-box)        # a fresh researcher+ token
ssh gpubox "AUTOLAB_TOKEN=$TOK autolab serve --project alice/nanochat"

Revoke it later with autolab token revoke gpu-box. See Tokens & API keys.

List & remove nodes

autolab nodes              # list the project's execution nodes
autolab nodes add          # how to attach a machine (prints the instructions)
autolab nodes rm <id>      # request shutdown + deregister a node (id or name)

---

Keep the agent and queue in view while nodes run with autolab status.