Runner configuration

Out of the box the runner needs exactly one thing: a runner-scoped API key in TB_API_KEY. Everything else has a sensible default. This page covers the two ways to configure it: plain environment variables for a single runner, or a runner.yaml for several profiles in one process.

Single-profile mode (env vars)

With no config file, the runner is one profile built from environment variables (set in the shell, a .env file next to the binary, or ~/.thoughtbridge-runner.json):

Key	Default	Meaning
TB_API_KEY	required	Runner-scoped ThoughtBridge API key.
TB_RUNNER_ID	runner-<hostname>	Stable id shown on runs and in the app’s runner registry.
TB_AGENT	claude	Which agent CLI drives sessions: claude, codex, or gemini.
TB_MODEL	agent’s default	Model passed to every session.
TB_AGENT_COMMAND	none	Your own skill or slash command (e.g. /my-orchestrator); the runner invokes it with the thought and steps back.
TB_WORKDIR	~/.thoughtbridge-runner/work	Where project repos are cloned.
TB_POLL_SECONDS	60	Queue poll interval.
TB_MAX_SESSIONS	3	Max concurrent agent sessions (always at most one per repo checkout).
TB_API_URL	production API	Override for self-hosted backends.
TB_CONFIG	none	Path to a runner.yaml (same as --config).
GOOGLE_CLOUD_PROJECT	none	Needed by the gemini CLI on Google accounts that require a GCP project.

Every setting is also available as a command-line flag; run the binary with --help for the full list. Keep the API key in .env or an inline environment variable rather than a flag: command-line arguments are visible to other processes.

Profiles - one process, several runners

To drive several agent identities from one process, put a runner.yaml next to where you run the binary (or point --config / TB_CONFIG at one):

apiKey: tb_...        # optional; TB_API_KEY still wins if set
profiles:
  - id: runner-codex
    agent: codex        # claude | codex | gemini (default claude)
    model: gpt-5-codex   # optional; the agent CLI's default when omitted
  - id: runner-gemini-flash
    agent: gemini
    model: gemini-2.5-flash

Each profile registers, polls, claims, and reports under its own id, so it appears as its own runner in the app and a project can be pinned to exactly one of them. Each profile also gets its own subdirectory under TB_WORKDIR, so two profiles never share a working copy even when they are assigned the same project, and poll loops are staggered so profiles do not hit the API in lockstep.

The shared settings (TB_API_URL, TB_WORKDIR, TB_AGENT_COMMAND, TB_POLL_SECONDS, TB_MAX_SESSIONS) apply to all profiles in the file.

Bad config fails fast at startup with the exact problem named: an unknown agent: value, a profile missing id, or two profiles sharing an id.

Running it

./thoughtbridge-runner-macos-arm64          # poll loop
./thoughtbridge-runner-macos-arm64 --once   # single pass - good for testing

# one-off, no files at all
TB_API_KEY=tb_... ./thoughtbridge-runner-macos-arm64 \
  --id runner-codex --agent codex --model gpt-5-codex

The same flags work identically when running from source (npm start / npm run once in the cloned repo).

Platform notes

macOS (Apple Silicon and Intel) and Linux x64 are fully supported with release binaries. Windows is deferred: the runner’s TypeScript is cross-platform, but the release pipeline is Unix-only today - use WSL with the run-from-source path in the meantime.