gaia conductor

The node agent: registers this machine's conductor for a project checkout, claims tickets, runs agents on them, and scaffolds a project's configuration. The operating guide is Run a conductor.

Synopsis

gaia [--conductor <name>] conductor [--log-level <level>] [--log-sink <sink>] <subcommand>

Global flags

Flag	Where	Effect
--conductor <name>	before conductor	select a conductor config by file stem: conductor → conductor.config.js, else <name>.conductor.config.js. Env: $GAIA_CONDUCTOR. Flag wins over env.
--log-level <level>	after conductor	debug · info (default) · warn · error. Env fallback GAIA_LOG_LEVEL. debug shows per-poll ticks, claims and idle cycles.
--log-sink <sink>	after conductor	stdout · file · both. Default both on a terminal, file otherwise. file/both write log.txt in the checkout's .gaia/ workspace root. Env fallback GAIA_CONDUCTOR_LOG.

Subcommands

Subcommand	Options	What it does
start	--foreground run the loop in this process (default: herdr-hosted) · --no-update-check skip the daily CLI update check	start the conductor loop
poll	—	run one conductor cycle, then exit
status	—	one line for this checkout's conductor
ls	—	one line per conductor the control plane holds for the current user — on any machine
stop	--now hard-kill via the host and let the server-side reaper mark it offline (default: graceful offline)	stop the conductor
reap	—	tear down herdr worktrees of finished-but-uncleaned tickets (orphans a live tick missed: conductor down at done, restarted, or reassigned)
init	see below	scaffold the project's engine config and the machine's context

The status line

status and ls print tab-separated columns:

<machine_id>	<liveness>	<project>	<label>	<workspace_root>
pg-Mac.fritz.box-gaia	online	gaia	pg-Mac.fritz.box-gaia	/Users/pascal/Projects/gaia

Liveness is derived, and it is the same three words the cockpit and the control plane use: online (heartbeating within its lease) · stale (registered as online but the heartbeat is old or the lease has lapsed) · offline (stopped or never reported).

init options

Option	Meaning
--base-url <url>	control-plane base URL (site.base_url) — required only when onboarding this machine
--project <name>	GAIA project name — required only to scaffold the committed repository config; omit for machine-only onboarding
--secret-env <VAR>	environment variable holding the OAuth client secret (else a terminal prompt)
--client-id <id>	OAuth consumer id (default gaia-agent)
--machine-id <id>	machine host token for the context (default: the hostname)
--user-id <id>	the developer's short id for the user-global context
--machine-path <path>	user-global machine context path (default ~/.gaia/machine.config.js)
--config <path>	target committed engine config path (default ./.gaia/conductor.config.js)
--force	overwrite an existing committed config
--reonboard	redo machine-context onboarding even if a context file exists

init is idempotent: an existing engine config is kept unless --force; the machine context is fill-only-missing — existing values always win, and --reonboard only reruns the onboarding questions on a machine that already has a context, still filling absent or blank keys only; outside a terminal, --secret-env and --user-id must be passed. It writes ./.gaia/conductor.config.js (committed; states: ['spec', 'diagnose', 'coding', 'review'], max_parallel: 5, DDEV worktree hooks, Claude Code as the agent), seeds ~/.gaia/gaia.config.js, and writes ~/.gaia/machine.config.js (mode 0600). See Connect a repository.

Files

Path	Role
./.gaia/conductor.config.js	the engine config — project, machine_id, states, max_parallel, worktree hooks, addons. Variants: ./.gaia/<name>.conductor.config.js.
./.gaia/conductor.config.local.js	optional, uncommitted local override (for example max_parallel)
~/.gaia/gaia.config.js	the default connection every repository inherits
~/.gaia/machine.config.js	identity and the client secret
<workspace_root>/.gaia/log.txt	the conductor log (file/both sinks)
.gaia-worktrees/<branch>	the per-ticket worktrees

Environment

Variable	Effect
GAIA_CONDUCTOR	default value for --conductor
GAIA_CONDUCTOR_CONFIG	explicit engine config path; wins over discovery
GAIA_LOG_LEVEL	default value for --log-level
GAIA_CONDUCTOR_LOG	default value for --log-sink

Next

• Run a conductor — the operating guide
• Engine config — every key of conductor.config.js
• Several conductors per repository — variants and selection