Connect a repository

You'll learn how gaia conductor init onboards your machine and scaffolds a repository, which files it writes and where, and how to authenticate afterwards.

Connecting a repository is one command. It does two jobs and works out which of them are still needed: onboarding this machine (once per machine) and setting up this repository (once per repository).

Before you start

The CLI installed and on your PATH — see Install the CLI.
The base URL of the GAIA control plane you are connecting to.
OAuth client credentials for that control plane: a client id (gaia-agent by default) and a client secret.
A project on the control plane that this repository maps to, and its name.

Run `gaia conductor init`

The first repository on a new machine does both jobs at once:

cd /path/to/your/repo

GAIA_CLIENT_SECRET='…' gaia conductor init \
  --base-url https://gaia.example.com \
  --project my-project \
  --user-id ada \
  --secret-env GAIA_CLIENT_SECRET

Every later repository on the same machine only needs the project — the machine context is already there:

cd /path/to/another/repo
gaia conductor init --project another-project

Omit --secret-env and, in a terminal, you are prompted for the secret instead; omit --user-id and you are prompted for that too. Outside a terminal both must be passed, and the command fails naming what is missing rather than writing a half-configured install.

Other flags: --client-id <id> (default gaia-agent), --machine-id <id> (defaults to the hostname), --config <path> to write the engine config somewhere other than ./.gaia/conductor.config.js, --machine-path <path> for a non-default machine context location.

What it writes

File	Committed?	Holds
`./.gaia/conductor.config.js`	yes	The engine config: this repository's `project`, the `machine_id` composition, the workflow `states` the conductor picks up (`spec`, `diagnose`, `coding`, `review` by default — not `qualification`), `max_parallel` (5), worktree lifecycle `hooks` (`ddev init-worktree` / `ddev delete -Oy` — edit these for a non-DDEV project), and the remote / executor / agent / workspace addons (Claude Code as the agent). No `site`, no `plugins`.
`~/.gaia/gaia.config.js`	no	The connection config — a `{ site, plugins }` file that `gaia ui`, `gaia dropsh` and the conductor's own auth all read. Seeded here if missing.
`~/.gaia/machine.config.js`	no, mode `0600`	Your machine context: `machine_id`, `user_id`, `base_url`, `client_id`, `client_secret`. Shared by every project on this machine, and the only file holding the secret.

The home connection config is the default connection every repository on this machine inherits. A project-local ./.gaia/gaia.config.js override is opt-in and init never writes one — create it only when a repository must reach a different control plane than your machine default. When present it genuinely overrides the machine context, base_url included.

Both files are covered key by key in Engine config and Connection config.

It is safe to re-run

init is idempotent and protects everything that already exists:

An existing engine config is kept, not overwritten — it says so and tells you to pass --force if replacing it is what you meant.
The machine context is fill-only-missing: existing values always win, with or without --reonboard — that flag only reruns the onboarding questions on a machine that already has a context, and still fills only absent or blank keys. To change a value that is already set — a rotated client secret, a new base URL — edit ~/.gaia/machine.config.js directly.
Running it with no --project on an already-onboarded machine just says so and exits.

Authenticate

Two OAuth profiles are declared in the connection config — session (the agent's own identity, the default) and pm (project-manager scope, for creating tickets and routing them by hand):

gaia dropsh auth login --provider session
gaia dropsh auth login --provider pm
gaia dropsh auth status   # both profiles present

Tokens are short-lived; gaia dropsh auth status shows until when each is valid, and a command that meets an expired token tells you to log in again.

Then commit ./.gaia/conductor.config.js. From here gaia conductor start runs the loop and gaia conductor status reports on it — but a conductor that picks up a ticket needs the repository's WORKFLOW.md to know what to do with it.

Author WORKFLOW.md — the file that tells a run which skills to load and what binds the work.
Run a conductor — start, status, stop.
Several conductors per repository — when one repository serves several GAIA projects.

Connect a repository ​

Before you start ​

Run gaia conductor init ​

What it writes ​

It is safe to re-run ​

Authenticate ​