Core concepts¶

A few ideas explain almost everything the CLI does.

Projects¶

A project is an optimization objective plus a baseline — your starting code (or, for an empty project, a prompt). It defines what you're optimizing and the point you're improving on. Example: minimize val_loss on top of a nanochat training script.

Every project has a display name ("My Cool Project") and a namespaced slug (alice/my-cool-project). The slug — username/slugified-name — is what you use in commands and URLs (autolab clone alice/my-cool-project). It's deduped to …-v2 if the name is taken.

Experiments are commits¶

Autolab treats research like git: an experiment is a commit. When you submit, the CLI snapshots your working tree, commits it, and queues it as one experiment. The agent's experiments are commits too. autolab log is your history and autolab graph draws the branch tree (what forked from where); → marks the experiment you're currently in.

This is why the workspace behaves like a git checkout: autolab diff shows your changes versus the experiment you're in, and autolab checkout <id> resets your working tree to any experiment's code.

The field bag, filled in stages¶

An experiment is a small bag of fields — name, description/idea, run command, setup, node constraint, and the code itself. You rarely fill all of them. You provide what you care about; the control node and agent fill the blanks (a name now, the run command and code at pickup).

Field locking¶

By default, every field you set is locked — the agent fills only the blanks and never overwrites your values. This makes submit predictable: what you typed is what runs.

--soft — let the agent refine the fields you set (it may revise your code or run command). Use it when you want a starting point, not a fixed spec.
--nocode — submit an idea only; ignore code changes and let the agent write the code.

Where you end up after submit follows one rule: you advance into the new experiment only when the code is final — i.e. you pushed code and didn't pass --soft. With --soft or --nocode, the code isn't yours-and-final, so you stay put in your current experiment. See Run experiments.

The autonomous loop¶

Once a project is live (autolab start), an LLM agent drives a loop:

Generate — propose hypotheses and queue experiments (if autogen is on).
Code — write the experiment's code.
Schedule — run it on an available execution node.
Analyze — read logs and metrics, decide what worked.
Merge — fold improvements into main; discard the rest.

You steer this loop from the CLI: pause/resume it, toggle idea generation, set the objective and constraints, or just queue your own experiments. See Drive the agent.

Control node vs. execution nodes¶

The control node (app.autolab.ai) hosts the agent, the queue, the dashboard, and each project's private git repo. You never run experiments here.
Execution nodes are machines you attach with autolab serve. They clone the project's code and actually run the jobs. They're assumed heterogeneous — attach whatever compute you have. Because a node clones private code, registering one needs a researcher+ token.

Platform key vs. provider keys¶

The agent needs an LLM provider key to do its work. Every project starts on your AutoLab platform key — the managed default, nothing to configure. To use your own provider account instead (Anthropic, OpenAI, …), add a key and assign it:

autolab keys add --provider anthropic
autolab keys use <key>

See Tokens & API keys.

The workspace (`.autolab/`)¶

A linked workspace keeps its state in a hidden .autolab/ directory:

.autolab/git — the workspace's version control. It is not a normal .git; autolab drives it through autolab verbs and hides it (and any nested .git from your own code) from its work tree.
.autolab/config.json — workspace metadata (which project this directory is linked to). If it's ever lost, the CLI rebuilds it from the git remote.

You don't edit these by hand — init, clone, submit, and checkout manage them. Details in Configuration & environment.