Quickstart¶

Go from install to a live, self-driving research project in about five minutes.

Prerequisites

A machine with git ≥ 2.38 and a working python/uv toolchain for your project. The installer bootstraps uv for you. See Install & setup for the full list.

1. Install¶

curl -fsSL https://app.autolab.ai/install.sh | sh

This installs the slim autolab CLI (just click, rich, httpx, pydantic). Check it:

autolab --version

autolab login

Opens a browser to sign in and stores a token for this host. On a headless box, use a token instead — see Tokens & API keys.

3. Teach your coding agent (optional)¶

Work with Claude Code or Codex? Install the AutoLab skill into it so it can drive AutoLab for you — set up projects, queue experiments, and steer the agent in plain language:

autolab install        # asks which tool(s); or: autolab install claude|codex|both

See Use from Claude Code & Codex for what the skill teaches.

4. Create a project¶

Point Autolab at the code you want to optimize. From inside your repo:

cd my-research-repo
autolab init

init asks a few questions — whether to use this directory's code, the project name, the run command (how one experiment runs, e.g. python train.py), and your objective (what to optimize, e.g. minimize validation loss). It creates the project live-but-paused: it shows up on the dashboard with the agent paused.

No code yet? Start from a blank slate

autolab init --empty --objective "maximize MMLU score"

The agent writes the experiment code itself from your objective.

Scripted / non-interactive (good for agents & CI)

autolab init -y \
  --name "nanochat" \
  --objective "minimize val loss" \
  --run "python train.py" \
  --start

5. Start the agent¶

autolab start

This seeds the baseline from your code and starts the agent. The first start takes the project live; afterwards, start resumes the agent after a pause.

6. Attach compute¶

Experiments run on execution nodes — machines you attach. Until one is online, queued experiments (the agent's and yours) simply wait. Turn any machine into a node:

autolab serve --project you/nanochat     # connects, then keeps running in the background

serve returns once the node is online and survives SSH disconnects — check it with autolab serve status, disconnect with autolab serve stop. For a remote GPU box or a Slurm cluster, see Execution nodes. Once a node is online, the agent starts working through the queue: it proposes an experiment, writes the code, runs it on a node, and analyzes the result — merging what works.

7. Queue your own experiment¶

You don't have to wait for the agent to have ideas — you can put your own work on the same queue. Every experiment goes through the same lifecycle:

submit → queued → a node picks it up and runs it → the agent analyzes the
result → merged (it improved the objective) or discarded

There are two ways to queue one:

# 1. Your code: edit files, check what would be sent, then submit it
autolab diff                              # changed files ±lines (-p for the full patch)
autolab submit -m "rotary embeddings"     # snapshot + queue exactly this code

# 2. Just an idea: the agent writes the code for it
autolab submit --nocode -m "try a cosine LR schedule"

submit snapshots your working tree (nothing needs to be committed by hand) and queues it as a new experiment. With no changes and no -m, there is nothing to submit and the CLI says so. See Run experiments for --soft seeds, field locking, and branching from a specific experiment.

8. Watch it run¶

autolab status          # the project + agent, nodes, and the experiment you're in
autolab log             # experiment history; → marks the experiment you're in
autolab open <id>       # an experiment's dashboard page — its run logs stream there
autolab open            # or the project dashboard itself

What next?¶

Understand the model

Why an experiment is a commit, and what "field locking" means.

Core concepts
Run experiments well

Code vs. --soft vs. --nocode, diffs, checkout, and cancel.

Run experiments
Tune the project

Objective, constraints, run command, cost caps, and collaborators.

Project settings