the_lab.api

Autonomous experiment management for AI research agents.
Let agents run experiments, branch ideas, and track metrics — hands-free.

The Lab is a lightweight API + dashboard that lets AI agents run structured research. No database, no setup beyond installing the CLI and running the-lab init.

Jump To: Quick Start, How It Works, Under the Hood

---

Quick Start

# User install — from the main branch, dashboard included, no Node.js needed
pipx install --force "git+https://github.com/LambdaLabsML/the_lab.api@main"
the-lab fetch-dashboard --tag main

# Or install from source while developing (needs Node.js >= 18 for the dashboard)
git clone https://github.com/LambdaLabsML/the_lab.api.git
cd the_lab.api
pip install -e .
./build-dashboard.sh

# Initialize your project (interactive — sets up prompts, MCP, gitignore)
cd /path/to/your/repo
the-lab init

# Start the API + dashboard
the-lab .

# Launch one agent turn, or keep it looping
the-lab-agent
the-lab-agent loop -d 15m

That's it. Open http://localhost:8000 and watch the agent work.

Install channels

The dashboard is compiled build output and is not in the git tree, so a plain pipx install git+… gives you a working API with the UI replaced by a "Dashboard not built" page. CI builds the dashboard and attaches it to releases; pick a channel:

	Command	Gets
main (latest code)	pipx install --force "git+https://github.com/LambdaLabsML/the_lab.api@main" the-lab fetch-dashboard --tag main	main HEAD + a dashboard built from it. Both commands are permanent.
tagged release (stable)	the-lab fetch-dashboard after installing, or the wheel URL from the latest release	The newest tagged version. The release wheel already contains the dashboard, so it is a single install.
clone (developing)	pip install -e . + ./build-dashboard.sh	Your working tree. Needs Node.js ≥ 18.

the-lab fetch-dashboard drops the compiled dashboard into an existing install at any time — no reinstall, no Node.js. It defaults to the latest tagged release (prereleases excluded) and takes --tag main for the rolling build. For a private repo, pass a token: GITHUB_TOKEN=$(gh auth token) the-lab fetch-dashboard.

See LambdaLabsML/the_lab.api.demo for a working example project.

the-lab . --port 9009           # bind a different port
the-lab . --host 127.0.0.1      # bind a different host
the-lab . --https               # self-signed HTTPS
the-lab . --serve-git           # authenticated, read-only Git clone/fetch
the-lab . --perf                # write .the_lab/api_perf.csv
the-lab-agent --role instructor # use .the_lab/PROMPT.instructor.md
the-lab-agent --sandbox on      # enable network + file sandbox
the-lab-agent --agent codex     # Codex instead of Claude
the-lab-agent list              # recent agent IDs, resume IDs, and commands
the-lab-agent --agent codex resume <session-id>  # continue a saved Codex conversation

the-lab-agent list combines Claude and Codex sessions in newest-first order. Use --provider claude|codex, --limit N, or --json to narrow or script the output. Internal Codex subagent threads are hidden unless --all is supplied.

Codex resume keeps its rollout in $CODEX_HOME/sessions (normally ~/.codex/sessions). The launcher reuses the session's registered worktree when available; if it was cleaned up, it resumes the conversation in a new agent worktree. Conversation history does not restore deleted, uncommitted files.

To enable HTTP Basic Auth, set credentials before starting the server — the agent and MCP bridge pick them up automatically from the same env vars:

export THE_LAB_USER=alice
export THE_LAB_PASSWORD=secret
the-lab .                  # server enforces auth
the-lab-agent              # agent authenticates automatically

To clone the lab repository directly from an instance, add --serve-git and bind the server to a reachable authenticated address:

THE_LAB_USER=<user> THE_LAB_PASSWORD=<password> the-lab . \
  --host 0.0.0.0 --https --serve-git
git clone https://<user>@<host>:8000/git/repository.git

Git will prompt for the password; use a credential helper rather than putting it in the URL. The endpoint supports clone and fetch only. Pushes and direct object-file requests are rejected. It exposes every commit reachable from the repository's advertised refs—including secrets committed in older history—but does not serve untracked working-tree files.

---

How It Works

1. the-lab init scaffolds .the_lab/PROMPT.md and optionally has Claude analyze your repo and fill it in — describe your research goal, background, and setup there
2. the-lab-agent registers an isolated per-agent worktree, then launches Claude or Codex with the MCP bridge attached
3. The agent calls get_instructions() to fetch the current prompt + API reference, creates ideas as git branches, runs experiments, and iterates
4. The dashboard shows progress in real time: metrics, graphs, tables, experiment logs, rendered output, agent state, prompts, sandbox config, and suggestions

Ideas form a DAG — each idea is a git branch that can fork from parents. Experiments and agents each run in isolated worktrees, so concurrent work does not collide.

Panes — the dashboard is a dockable layout; every pane can be floated, resized, or hidden to the tray:

Pane	What it shows / does
Filters	Global filter bar — by tag, status, experiment mode; affects all charts and table
Metrics	Line chart of any logged metric over time — log scale, outlier clipping, best-line overlay, colorblind palette
Scatter	Cross-metric scatter — plot any two metrics against each other
Table	Sortable multi-metric comparison across all experiments
Graph	Idea DAG — relationships, status, and improvement at a glance
Timeline	Experiments and notes interleaved chronologically
Log	Live experiment log viewer with full-text search
Detail	Per-idea drill-down: experiments, notes, log, output, script, diff
Agents	Active and past agent sessions — output log, token cost, resume command
Queue	Running and queued experiments; priority and resource assignment
Messages	Inter-agent messages grouped into titled threads (public or private) that agents can search, join and close
Sandbox	Network allow/deny lists + per-path file rules (rw / ro / hidden)
Prompts	Edit role-specific PROMPT.<role>.md files; copy agent launch command
Task	Current task description and status
Stats	API request timing and sizes
Suggest	Submit a new idea directly from the dashboard — it reaches agents as a suggestion thread they can discuss
API	Inline API reference

---

Under the Hood

• No database — all state in .the_lab/ as JSON files (gitignored, created automatically)
• Ideas are git branches — checkout, uncommitted changes carry to the new branch automatically
• Isolated worktrees — each experiment and each agent gets its own git worktree; concurrent runs never collide
• Survives restarts — running experiments re-attach on server startup
• MCP + curl — agents use typed MCP tools or plain HTTP, both work
• Sandbox — rootlesskit + bubblewrap + transparent proxy; default-deny network with per-path file rules (rw / ro / hidden)
• Auth — optional Basic Auth; scoped bearer tokens for experiment callbacks