Skip to content

Configuration & environment

Global flags

These apply to every command:

Flag Meaning
--url TEXT Control-node URL (overrides AUTOLAB_URL / profile).
--profile TEXT Named profile from ~/.config/autolab/config.toml.
-q, --quiet Print only essential results.
-v, --verbose Stream raw git output (useful for debugging).
--version Show the version and exit.

Choosing a host

The CLI talks to https://app.autolab.ai by default. The control-node URL is resolved in this order:

  1. --url flag
  2. AUTOLAB_URL environment variable
  3. the active profile's url
  4. https://app.autolab.ai
autolab --url http://localhost:8080 status   # one command
export AUTOLAB_URL=http://localhost:8080       # this shell

Your token is then looked up for the resolved host, so logins for different hosts never collide.

Profiles

Define named profiles in ~/.config/autolab/config.toml (hand-edited; the CLI only reads it):

default_profile = "prod"

[profiles.prod]
url = "https://app.autolab.ai"

[profiles.local]
url = "http://localhost:8080"

autolab --profile local status
export AUTOLAB_PROFILE=local        # or set it for the shell

Environment variables

Variable Used for
AUTOLAB_URL Control-node URL (beats profiles; see precedence above).
AUTOLAB_PROFILE Selects a named profile.
AUTOLAB_TOKEN Bearer token for control-node requests; used ahead of the stored login. Ideal for CI / SSH / headless.
AUTOLAB_HOME Root dir for execution-node workspaces (serve). Default ~/.autolab.
XDG_CONFIG_HOME Base for config ($XDG_CONFIG_HOME/autolab); defaults to ~/.config.

Config files

Stored under ~/.config/autolab/ (or $XDG_CONFIG_HOME/autolab/):

  • config.toml — hand-editable. Named profiles and default_profile. The CLI never writes it.
  • credentials.json — tool-managed, written by autolab login. Maps each host to its {token, username}. Written owner-only (mode 0600) because tokens are secrets.

The .autolab workspace

A directory linked to a project (via init or clone) keeps its state in a hidden .autolab/ folder:

  • .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 via the repo-local info/exclude. That's why you use autolab diff/autolab checkout, not raw git, inside a workspace.
  • .autolab/config.json — workspace metadata (which project this directory is linked to). If it's lost, the CLI rebuilds it from the git remote on the next command.

You never edit these by hand. submit snapshots and pushes the work tree to your create-only exp/u/<name>/* namespace and queues the experiment.

Execution-node workspaces

When this machine runs as a node (autolab serve), its working trees live under:

<AUTOLAB_HOME>/<hostname>/projects/<owner>--<slug>/

AUTOLAB_HOME defaults to ~/.autolab. The hostname namespacing keeps a shared NFS root collision-safe across machines.

See the full command surface in the CLI reference.