Skip to content

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; → 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:

  1. Generate — propose hypotheses and queue experiments (if autogen is on).
  2. Code — write the experiment's code.
  3. Schedule — run it on an available execution node.
  4. Analyze — read logs and metrics, decide what worked.
  5. 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.