Agents

Supported agents

Agent	Auth	Description
Claude	OAuth*, API key	Anthropic Claude Code
Codex	OAuth*, API key	OpenAI Codex CLI
Vibe	API key	Mistral Vibe
Copilot	—	GitHub Copilot (not proxied yet)
Blablador	API key	Helmholtz Blablador via OpenCode
KISSKI	API key	KISSKI AcademicCloud via OpenCode

* OAuth support for Claude and Codex is experimental.

Tools

Optionally available in the container:

Tool	Auth	Description
gh	OAuth, API key	GitHub CLI
glab	API key	GitLab CLI
SonarCloud	API key	SonarCloud scanner

Sidecar tools

Tools run in a separate container:

Tool	Auth	Description
CodeRabbit	API key	CodeRabbit code review

Listing agents

terok-executor agents list           # coding agents only
terok-executor agents list --all     # include tools (gh, glab, coderabbit, sonarcloud)

Setting the global default

The same selection string that terok-executor build --agents … accepts also drives the global default that's baked into L1 images when a project does not override image.agents:

terok-executor agents set                # interactive picker
terok-executor agents set all            # every roster entry
terok-executor agents set claude,vibe    # explicit list
terok-executor agents set all,-vibe      # everything except vibe

The value lands in ~/.config/terok/config.yml under image.agents by default — /etc/terok/config.yml when running as root, or whatever TEROK_CONFIG_FILE points at when that env var is set. Validation runs against the installed roster up front, so the file never references a name that won't resolve at build time.

Authentication

Three auth paths depending on the provider:

OAuth / interactive login (Claude, Codex, gh) — launches a temporary container with the vendor CLI. After login, the OAuth token is captured to the host-side credential database.

terok-executor auth claude

Interactive API key prompt (Vibe, Blablador, KISSKI, glab) — prompts for a key on the terminal. No container needed.

terok-executor auth vibe

Non-interactive (all providers) — pass the key directly:

terok-executor auth gh --api-key ghp_…

After authentication, containers receive phantom tokens instead of real credentials. See Security for how this works.

Running sidecar tools

Sidecar tools like CodeRabbit run via run-tool. Arguments after -- are passed to the tool binary:

terok-executor run-tool coderabbit . -- --pr 42

Custom agents

Place YAML files in ~/.config/terok/agent/agents/. The roster merges user definitions with bundled ones using deep merge for dicts and _inherit splicing for lists.

See the bundled definitions in resources/agents/ for the schema: binary, headless flags, vault routing, auth modes, and git identity.

Git identity

By default, agents commit under a built-in AI identity. To use the host machine's git config instead:

terok-executor run claude . --git-identity-from-host -p "…"

This injects user.name and user.email from the host's git config into the container.