AI Assistants

You must configure at least one AI assistant. All four can be configured and mixed within workflows.

Structured output guarantees

When a workflow node sets output_format, the guarantee level depends on the provider’s tier (exposed as capabilities.structuredOutput on GET /api/providers):

Provider	Tier	How it works	On a validation miss
Claude, Codex, OpenCode	enforced	The SDK/backend grammar-constrains decoding (`output_config.format` / `outputSchema` / `format:{json_schema}`).	The node fails — a refusal or `max_tokens` truncation can still bypass grammar enforcement, so the parsed output is validated post-parse for these too. No reask (a failure here is a genuine edge).
Pi, Copilot	best-effort	The schema is appended to the prompt; JSON is extracted from the response and structurally repaired (trailing commas, single quotes, truncated tails).	The executor re-asks (prompt + the schema errors) up to 3×; if still invalid, the node fails loudly.

In all cases the parsed output is validated against your output_format schema before downstream nodes see it, and a node that declares output_format but produces no schema-valid output fails rather than silently degrading. See Authoring Workflows → output_format for field-access ($node.output.field) semantics.

Claude Code

Recommended for Claude Pro/Max subscribers.

Archon does not bundle Claude Code. Install it separately, then in compiled Archon binaries, point Archon at the executable. In dev (bun run), Archon finds it automatically via node_modules.

Install Claude Code

Anthropic’s native installer is the primary recommended install path:

macOS / Linux / WSL:

curl -fsSL https://claude.ai/install.sh | bash

Windows (PowerShell):

irm https://claude.ai/install.ps1 | iex

Alternatives:

macOS via Homebrew: brew install --cask claude-code
npm (any platform): npm install -g @anthropic-ai/claude-code
Windows via winget: winget install Anthropic.ClaudeCode

See Anthropic’s setup guide for the full list and auto-update caveats per install path.

Binary path configuration (compiled binaries only)

In compiled Archon binaries, if claude is not on the default install path Archon autodetects, supply the path via either:

Environment variable (highest precedence):
```
CLAUDE_BIN_PATH=/absolute/path/to/claude
```

Config file (~/.archon/config.yaml or a repo-local .archon/config.yaml):

assistants:
  claude:
    claudeBinaryPath: /absolute/path/to/claude

Autodetect (zero-config fallback): Archon probes ~/.local/bin/claude (POSIX) and %USERPROFILE%\.local\bin\claude.exe (Windows), matching the native curl/PowerShell installer layouts.

If none of the three resolves in a compiled binary, Archon throws with install instructions on first Claude query.

The Claude Agent SDK accepts the native compiled binary, a JS cli.js, or the npm platform-package directory (e.g. @anthropic-ai/claude-code-win32-x64) — directories are auto-expanded to the contained claude/claude.exe.

Dev mode override: when running from source (bun run dev:server), the SDK auto-resolves its bundled per-platform binary by default. Set CLAUDE_BIN_PATH if you need to override that — most commonly on glibc Linux where the SDK picks the musl variant first and fails to spawn. Config-file claudeBinaryPath is intentionally binary-mode-only (per-repo, not per-machine).

Typical paths by install method:

Install method	Typical executable path
Native curl installer (macOS/Linux)	`~/.local/bin/claude`
Native PowerShell installer (Windows)	`%USERPROFILE%\.local\bin\claude.exe`
Homebrew cask	`$(brew --prefix)/bin/claude` (symlink)
npm global install	`$(npm root -g)/@anthropic-ai/claude-code/cli.js`
npm platform-package directory (Windows)	`$(npm root -g)/@anthropic-ai/claude-code-win32-x64` — directory accepted, auto-expanded to `claude.exe`
Windows winget	Resolvable via `where claude`
Docker (`ghcr.io/coleam00/archon`)	Pre-set via `ENV CLAUDE_BIN_PATH` in the image — no action required

If in doubt, which claude (macOS/Linux) or where claude (Windows) will resolve the executable on your PATH after any of the installers above.

Authentication Options

Claude Code supports three authentication modes via CLAUDE_USE_GLOBAL_AUTH:

Global Auth (set to true): Uses credentials from claude /login
Explicit Tokens (set to false): Uses tokens from env vars below
Auto-Detect (not set): Uses tokens if present in env, otherwise global auth

Option 1: Global Auth (Recommended)

CLAUDE_USE_GLOBAL_AUTH=true

Option 2: OAuth Token

# Install Claude Code CLI first: https://docs.claude.com/claude-code/installation
claude setup-token

# Copy the token starting with sk-ant-oat01-...

CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-xxxxx

Option 3: API Key (Pay-per-use)

Visit console.anthropic.com/settings/keys
Create a new key (starts with sk-ant-)

CLAUDE_API_KEY=sk-ant-xxxxx

Claude Configuration Options

You can configure Claude’s behavior in .archon/config.yaml:

assistants:
  claude:
    model: sonnet  # or 'opus', 'haiku', 'claude-*', 'inherit'
    settingSources:
      - project      # Default: only project-level CLAUDE.md
      - user         # Optional: also load ~/.claude/CLAUDE.md
    # Optional: absolute path to the Claude Code executable.
    # Required in compiled Archon binaries if CLAUDE_BIN_PATH is not set.
    # claudeBinaryPath: /absolute/path/to/claude

The settingSources option controls which CLAUDE.md, skill, command, and agent files the Claude Code SDK loads. The default is ['project', 'user'], which loads both the project-level <cwd>/.claude/ and your personal ~/.claude/. Set it to ['project'] if you want to scope a workflow to project-only resources.

Set as Default (Optional)

If you want Claude to be the default AI assistant for new conversations without codebase context, set this environment variable:

DEFAULT_AI_ASSISTANT=claude

Codex

Archon does not bundle the Codex CLI. Install it, then authenticate.

Install the Codex CLI

# Any platform (primary method):
npm install -g @openai/codex

# macOS alternative:
brew install codex

# Windows: npm install works but is experimental.
# OpenAI recommends WSL2 for the best experience.

Native prebuilt binaries (.dmg, .tar.gz, .exe) are also published on the Codex releases page for users who prefer a direct binary — drop one in ~/.archon/vendor/codex/codex (or codex.exe on Windows) and Archon will find it automatically in compiled binary mode.

See OpenAI’s Codex CLI docs for the full install matrix.

Binary path configuration (compiled binaries only)

In compiled Archon binaries, if codex is not on the default PATH Archon expects, supply the path via either:

Environment variable (highest precedence):
```
CODEX_BIN_PATH=/absolute/path/to/codex
```

Config file (~/.archon/config.yaml):

assistants:
  codex:
    codexBinaryPath: /absolute/path/to/codex

Vendor directory (zero-config fallback): drop the native binary at ~/.archon/vendor/codex/codex (or codex.exe on Windows).
Autodetect (zero-config fallback): if the vendor directory is empty, Archon probes the common npm-global install layouts: ~/.npm-global/bin/codex (POSIX), /opt/homebrew/bin/codex (macOS Apple Silicon), /usr/local/bin/codex (macOS Intel and Linux), %APPDATA%\npm\codex.cmd and %USERPROFILE%\.npm-global\codex.cmd (Windows). For other npm prefixes or custom layouts, set CODEX_BIN_PATH or the config path explicitly.

Dev mode (bun run) does not require any of the above — the SDK resolves codex via node_modules.

Authenticate

codex login

# Follow browser authentication flow

Extract Credentials from Auth File

On Linux/Mac:

cat ~/.codex/auth.json

On Windows:

type %USERPROFILE%\.codex\auth.json

Set Environment Variables

Set all four environment variables in your .env:

CODEX_ID_TOKEN=eyJhbGc...
CODEX_ACCESS_TOKEN=eyJhbGc...
CODEX_REFRESH_TOKEN=rt_...
CODEX_ACCOUNT_ID=6a6a7ba6-...

Codex Configuration Options

You can configure Codex’s behavior in .archon/config.yaml:

assistants:
  codex:
    model: gpt-5.3-codex
    modelReasoningEffort: medium  # 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
    webSearchMode: live           # 'disabled' | 'cached' | 'live'
    additionalDirectories:
      - /absolute/path/to/other/repo

Set as Default (Optional)

If you want Codex to be the default AI assistant for new conversations without codebase context, set this environment variable:

DEFAULT_AI_ASSISTANT=codex

Skills

Codex supports skills via filesystem auto-discovery from .agents/skills/. Run archon skill install (or archon setup) to install the bundled archon and manage-run skills for both Claude Code and Codex.

See Per-Node Skills for behavior details and limitations.

OpenCode (Community Provider)

SDK-backed community provider. Archon’s OpenCode adapter uses @opencode-ai/sdk, which provides a multi-provider AI coding agent with support for Anthropic, OpenAI, Google, and more through a unified interface.

OpenCode is registered as builtIn: false — like Pi, it is a bundled community provider rather than a core built-in.

Archon always runs OpenCode as a managed embedded runtime — it spawns and owns the OpenCode server process, generates a random server password per session, and tears it down when the workflow completes. Connecting to an external OpenCode server (baseUrl) is not supported.

Install

OpenCode is included as a dependency of @archon/providers — bun install pulls in the SDK automatically. It’s available immediately.

Authenticate

OpenCode handles authentication internally — Archon does not pass API keys through config. Configure credentials using one of these methods:

/connect TUI command — Run opencode in your terminal, then use the /connect command to interactively authenticate with your chosen provider
Config file — Store credentials in ~/.config/opencode/opencode.json with {env:VAR} or {file:PATH} substitution
Auth file — Credentials are persisted in ~/.local/share/opencode/auth.json after connecting

OpenCode delegates to the underlying LLM provider (Anthropic, OpenAI, Google, etc.) based on your model selection. Request-scoped env vars from Archon workflows are still merged into the OpenCode environment.

Configuration Options

assistants:
  opencode:
    model: anthropic/claude-3-5-sonnet  # Required: '<provider>/<model>' format
    # or build-in agent
    agent: general

Model reference format

OpenCode models use a <provider>/<model> format. List all available models via opencode models:

assistants:
  opencode:
    model: anthropic/claude-3-5-sonnet   # via Anthropic
    # model: openai/gpt-4o                # via OpenAI
    # model: google/gemini-2.5-pro        # via Google

Supported Archon Features

Feature	Support	Notes
Session resume	✅	Single-agent runs return `sessionId`; multi-agent runs do not
MCP servers	✅	`mcp: path/to/servers.json` passed through to OpenCode
Structured output	✅	`output_format:` — schema passed to OpenCode SDK
System prompt override	✅	`systemPrompt:`
Codebase env vars (`envInjection`)	✅	merged into the spawned OpenCode environment
Skills	✅	SKILL.md files with YAML frontmatter, pattern-based permissions
Tool restrictions	✅	`tools` / `disallowedTools` per agent; deny wins over allow
Inline agents (`agents:`)	✅	File-materialized agents; single and parallel multi-agent fan-out
Hooks	✅	Plugin hook system (tool, session, message hooks)
Effort / reasoning control	❌	No per-request param; not configurable in agent file, opencode puts it in config.
Thinking control	❌	No explicit `thinking` field in agent frontmatter; OpenCode auto-enables reasoning when `agents[].model` is a reasoning-capable model (e.g. `anthropic/claude-sonnet-4-5`)
Fallback model	❌	No native failover in the SDK
Sandbox	❌	Not native in the SDK; Archon uses worktree isolation
Cost limits (`maxBudgetUsd`)	❌	Cost tracked in result chunks, but no runtime budget enforcement

Unsupported YAML fields trigger a visible warning from the dag-executor when the workflow runs, so you always know what was ignored.

Usage in workflows

name: my-workflow
provider: opencode
model: anthropic/claude-3-5-sonnet

nodes:
  - id: analyze
    prompt: "Analyze the codebase structure"
    # per-node model override:
    # model: openai/gpt-4o

Pi (Community Provider)

One adapter, ~20 LLM backends. Pi (@earendil-works/pi-coding-agent) is a community-maintained coding-agent harness that Archon integrates as the first community provider. It unlocks Anthropic, OpenAI, Google (Gemini + Vertex), Groq, Mistral, Cerebras, xAI, OpenRouter, Hugging Face, and local inference (LM Studio, ollama, llamacpp, custom OpenAI-compatible endpoints registered in ~/.pi/agent/models.json) under a single provider: pi entry.

Pi is registered as builtIn: false — it validates the community-provider seam rather than being a core-team-maintained option. If it proves stable and valuable it may be promoted to builtIn: true later.

Install

Pi is included as a dependency of @archon/providers — no separate install needed. It’s available immediately.

Quick setup via wizard

Run archon setup and select Pi (community) in the AI assistant multiselect. The wizard prompts for your preferred backend and API key, writes the key to ~/.archon/.env, and writes the model ref to ~/.archon/config.yaml automatically.

Authenticate

Pi supports both OAuth subscriptions and API keys. Archon’s adapter reads your existing Pi credentials from ~/.pi/agent/auth.json (written by running pi → /login) AND from env vars — env vars take priority per-request so codebase-scoped overrides work.

OAuth subscriptions (run pi /login locally):

Anthropic Claude Pro/Max
OpenAI ChatGPT Plus/Pro
GitHub Copilot
Google Gemini CLI
Google Antigravity

API keys (env vars):

Pi provider id	Env var
`anthropic`	`ANTHROPIC_OAUTH_TOKEN` (subscription, read first) or `ANTHROPIC_API_KEY`
`openai`	`OPENAI_API_KEY`
`google`	`GEMINI_API_KEY`
`groq`	`GROQ_API_KEY`
`mistral`	`MISTRAL_API_KEY`
`cerebras`	`CEREBRAS_API_KEY`
`xai`	`XAI_API_KEY`
`openrouter`	`OPENROUTER_API_KEY`
`huggingface`	`HF_TOKEN`

The full backend → env-var map is generated from the installed Pi SDK (bun run generate:pi-vendor-map) and covers every key-based backend (DeepSeek, Together, Fireworks, Azure OpenAI, Vercel AI Gateway, Cloudflare, MiniMax, Moonshot, Z.AI, Xiaomi, …). Amazon Bedrock and Google Vertex authenticate via ambient cloud credentials (AWS chain / gcloud ADC) instead of a pasted key.

Local / custom providers (no credentials needed):

Providers that aren’t in the env-var table above (LM Studio, ollama, llamacpp, custom OpenAI-compatible endpoints) work without any Archon-side configuration. Register them in ~/.pi/agent/models.json per Pi’s own docs and reference them as <pi-provider-id>/<model-id>:

assistants:
  pi:
    model: lm-studio/qwen2.5-coder-14b   # whatever ID you registered with Pi

Archon logs an info-level pi.auth_missing event when no credentials are found and continues — Pi’s SDK then connects directly to the local endpoint defined in models.json. If the provider does require auth (a less-common cloud backend not in the env-var table) the SDK call fails downstream; the pi.auth_missing breadcrumb in the log lets you trace it back to a missing env-var mapping.

Pi settings (baseline behavior)

Archon reads your Pi settings files as the starting point for every session:

~/.pi/agent/settings.json — global Pi preferences (retry counts, transport, compaction strategy, thinking budgets, default model, etc.)
<repo>/.pi/settings.json — project-level overrides on top of global

All settings flow in automatically. You do not need to re-state them in Archon’s config.yaml. To configure baseline Pi settings, edit ~/.pi/agent/settings.json directly.

Archon never writes back to these files — ~/.pi/agent/settings.json is read-only from Archon’s perspective. Session-level changes (model switches, thinking-level adjustments) are held in memory only and discarded when the session ends, matching Claude and Codex behavior.

If Pi settings files do not exist (Docker, first-time setup, compiled binary with no Pi home directory), Archon falls back to Pi SDK defaults. Parse errors in the settings files are logged as warnings (pi.settings_load_error) and never prevent the session from starting.

Extensions (on by default)

A major reason to pick Pi is its extension ecosystem: community packages (installed via pi install npm:<package>) and your own local ones that hook into the agent’s lifecycle. Extensions can intercept tool calls, gate execution on human review, post to external systems, render UIs — anything the Pi extension API exposes.

Archon turns extensions on by default. To opt out in .archon/config.yaml:

assistants:
  pi:
    enableExtensions: false   # skip extension discovery entirely
    # interactive: false       # keep extensions loaded, but give them no UI bridge

Most extensions need three config surfaces:

Surface	Purpose
`extensionFlags`	Per-extension feature flags (maps 1:1 to Pi’s `--flag` CLI switches)
`env`	Env vars the extension reads at runtime (managed via `.archon/config.yaml` or the Web UI codebase env panel)
Workflow-level `interactive: true`	Required for approval-gate extensions on the web UI — forces foreground execution so the user can respond

Example — plannotator (human-in-the-loop plan review):

# One-time install into your Pi home
pi install npm:@plannotator/pi-extension

assistants:
  pi:
    model: anthropic/claude-haiku-4-5
    extensionFlags:
      plan: true              # enables the plannotator "plan" flag
    env:
      PLANNOTATOR_REMOTE: "1" # exposes the review URL on 127.0.0.1:19432 so you can open it from anywhere

name: my-piv
provider: pi
interactive: true             # plannotator gates the node on human approval — required on web UI

When the node runs, plannotator prints a review URL and blocks until you click approve/deny in the browser. Archon’s CLI/SSE batch buffer flushes that URL to you immediately so you never get stuck waiting on a node that silently wants input.

Model reference format

Pi models use a <pi-provider-id>/<model-id> format:

assistants:
  pi:
    model: anthropic/claude-haiku-4-5       # via Anthropic
    # model: google/gemini-2.5-pro           # via Google
    # model: groq/llama-3.3-70b-versatile   # via Groq
    # model: openrouter/qwen/qwen3-coder    # via OpenRouter (nested slashes allowed)

Usage in workflows

name: my-workflow
provider: pi
model: anthropic/claude-haiku-4-5

nodes:
  - id: fast-node
    provider: pi
    model: groq/llama-3.3-70b-versatile   # per-node override — switches backends
    prompt: "..."
    effort: low
    allowed_tools: [read, grep]            # Pi's built-in tools: read, bash, edit, write, grep, find, ls

  - id: careful-node
    provider: pi
    model: anthropic/claude-opus-4-5
    prompt: "..."
    effort: high
    skills: [archon-dev]                   # Archon name refs work — see Pi capabilities below

Pi capabilities

Feature	Support	YAML field
Extensions (community + local)	✅ (default on)	`enableExtensions: false` to disable; `interactive: false` to load without UI bridge; `extensionFlags: { <name>: true }` per extension
Session resume	✅	automatic (Archon persists `sessionId`)
Tool restrictions	✅	`allowed_tools` / `denied_tools` (read, bash, edit, write, grep, find, ls)
Thinking level	✅	`effort: low\|medium\|high\|max` (max → xhigh)
Skills	✅	`skills: [name]` (searches `.agents/skills`, `.claude/skills`, user-global)
Inline sub-agents	❌	`agents:` is Claude-only; ignored with a warning on Pi
System prompt override	✅	`systemPrompt:`
Codebase env vars (`envInjection`)	✅	`.archon/config.yaml` `env:` section
MCP servers	❌	Pi rejects MCP by design
In-process native tools	✅	none — Archon’s `manage_run` tool is auto-injected in project-scoped chat via Pi `customTools` (distinct from MCP, which Pi rejects). Gated on the `nativeTools` provider capability.
Claude-SDK hooks	❌	Claude-specific format
Structured output	✅ (best-effort)	`output_format:` — schema is appended to the prompt and JSON is parsed out of the assistant text. Handles bare JSON, `json`-fenced, reasoning-model prose preambles like `Let me evaluate... {...}` (Minimax M2.x pattern), and structurally-corrupt JSON (trailing commas, single quotes, truncated tails) via repair. The parsed output is then validated against the schema; on a miss the executor re-asks (prompt + the schema errors) up to 3×, and only then fails the node (it no longer degrades silently to a warning). Not SDK-enforced like Claude/Codex.
Cost limits (`maxBudgetUsd`)	❌	tracked in result chunk, not enforced
Fallback model	❌	not native in Pi
Sandbox	❌	not native in Pi

Unsupported YAML fields trigger a visible warning from the dag-executor when the workflow runs, so you always know what was ignored.

GitHub Copilot (Community Provider)

Use a GitHub Copilot subscription inside Archon workflows. Drives the Copilot CLI via @github/copilot-sdk, supporting OpenAI, Anthropic via BYOK, Gemini, and the other models Copilot exposes — switch between them with the model field.

Copilot is registered as builtIn: false — like Pi, a bundled community provider rather than a core built-in.

Install

For source installs (bun run), the SDK + its bundled CLI dependency come along with bun install — nothing extra to do.

For compiled Archon binaries, install the Copilot CLI yourself and point Archon at it:

npm install -g @github/copilot

Then tell Archon where the binary lives (the resolver searches these in order):

COPILOT_BIN_PATH=/absolute/path/to/copilot

assistants:
  copilot:
    copilotCliPath: /absolute/path/to/copilot

Or place the binary at ~/.archon/vendor/copilot/copilot (POSIX) / ~/.archon/vendor/copilot/copilot.exe (Windows) and the resolver picks it up automatically.

Authenticate

By default, Copilot uses the credentials from your local copilot login. Generic GH_TOKEN / GITHUB_TOKEN env vars are not picked up automatically — classic GitHub PATs lack Copilot entitlement and would fail with a misleading SDK error. Auth precedence (highest to lowest):

COPILOT_GITHUB_TOKEN (env) — always wins when set; treated as explicit Copilot intent
useLoggedInUser: false in .archon/config.yaml — opts into env-token auth, including generic GH_TOKEN / GITHUB_TOKEN
copilot login credentials — the default

An active GitHub Copilot subscription is required for any of these to work.

Copilot Configuration Options

You can configure Copilot’s behavior in .archon/config.yaml:

assistants:
  copilot:
    model: gpt-5-mini             # 'gpt-5', 'gpt-5-mini', 'claude-sonnet-4.5', 'auto', etc.
    modelReasoningEffort: medium  # 'low' | 'medium' | 'high' | 'xhigh' | 'max' (alias for xhigh)
    # configDir: /absolute/path/to/copilot-config
    # enableConfigDiscovery: false  # only enable for trusted repos — bypasses Archon's workflow MCP/skill validation
    # useLoggedInUser: false        # opt into env-token auth (GH_TOKEN / GITHUB_TOKEN); default uses `copilot login`
    # logLevel: error               # 'none' | 'error' | 'warning' | 'info' | 'debug' | 'all'

Copilot accepts OpenAI models (gpt-5, gpt-5-mini), Anthropic via BYOK (claude-sonnet-4.5), Gemini, and more. When no model is configured, Archon passes model: 'auto' and Copilot picks.

Supported Archon Features

Feature	Support	Notes
Session resume	✅	Returns `sessionId`; reused on resume
Reasoning control	✅	`effort:` / string `thinking:` → Copilot `reasoningEffort`; `max` maps to SDK `xhigh`
System prompt override	✅	`systemPrompt:`
Codebase env vars	✅	merged into the spawned Copilot CLI environment
Tool restrictions	✅	`allowed_tools` → `availableTools`, `denied_tools` → `excludedTools`
MCP servers	✅	`mcp: path/to/servers.json` → `SessionConfig.mcpServers` (env vars `$FOO` expanded; missing vars warned)
Skills	✅	`skills: [name]` resolved from `.agents/skills/` or `.claude/skills/` (project or home) → `SessionConfig.skillDirectories`
Structured output	✅	best-effort via prompt augmentation + repair; the parsed output is validated against the schema, the executor re-asks up to 3× on a miss, then fails the node (no longer a silent warning)
Sub-agents (`agents:`)	✅	`name`/`description`/`prompt`/`tools` → `SessionConfig.customAgents`; Claude-specific fields (`model`, `disallowedTools`, `skills`, `maxTurns`) warn per agent and are ignored
Fork-session retry	⚠️	Copilot SDK has no fork API — when Archon requests a fork (on retry), we create a fresh session and emit a system-chunk warning
Hooks	❌	Archon hooks ≠ Copilot’s `SessionHooks` event vocabulary
Fallback model	❌	not wired
Cost control	❌	no cost-limit API
Sandbox	❌	Copilot permissions surface is separate from Archon’s sandbox model

Set as Default (Optional)

DEFAULT_AI_ASSISTANT=copilot

Per-user credentials and AI Settings

Everything above configures the install-wide assistant credentials (env vars, claude /login, etc.) — every run uses the same shared keys. On a shared Archon box where several people use the same server, each user can instead connect their own provider — by API key or subscription — so their runs and chats bill to them, not to the install’s shared key.

When you need this

You run Archon for a team and want each person to bring their own provider key or Claude Pro/Max / Copilot subscription.
You want a personal key isolated from the shared install key.

Solo users don’t need any of this — the install-wide setup above is enough.

Enabling it

The credential vault is available on every install — Archon auto-provisions a local key at ~/.archon/credential-key on first use. No setup required for a solo install.

If you’re running a managed or multi-user deploy and want to control the encryption key yourself (e.g. to rotate it, share it across containers, or keep it in a secrets manager), set TOKEN_ENCRYPTION_KEY and the local key file is skipped entirely:

# .env — generate with: openssl rand -hex 32
TOKEN_ENCRYPTION_KEY=<64-char hex>

Rotating TOKEN_ENCRYPTION_KEY (or deleting ~/.archon/credential-key) invalidates all stored user credentials — everyone must reconnect. archon doctor will report a mass_decrypt_failure and include a re-connect hint if this happens.

Connecting from the console

The console AI Settings page (Settings in the web UI) has four sections:

Model Tiers — map the small / medium / large tiers to a provider + model (and optional effort). This writes the install’s tiers: config and works on any install, even without TOKEN_ENCRYPTION_KEY (it’s non-secret config). Pi tier models show a cost/reasoning/context hint from Pi’s model catalog.
Model Aliases — define @custom refs (e.g. @fast) usable in workflow model: fields, with the same scope toggle.
Agents — one card per agent (Claude Code, Codex, Pi, OpenCode, Copilot) with the credentials it can spend nested inside, each card showing a readiness state (ready / needs credential). Connect a credential for your user inside the agent that uses it. Credentials are keyed by vendor (anthropic, openai, github-copilot, openrouter, …), and one credential serves every agent that consumes it (an anthropic key powers Claude Code and Pi’s anthropic backend — both cards reflect it). Every vendor accepts an API key; anthropic, openai, and github-copilot additionally offer subscription login (an OAuth flow — for openai/ChatGPT it is an Archon-owned PKCE flow where you paste the redirect URL or code back, #1924). Legacy ids (claude/codex/copilot) are accepted and normalized. The Pi card keeps its 30+ backends behind a searchable “Add backend…” picker (with model counts from Pi’s catalog) and shows ambient chains (Amazon Bedrock, Google Vertex) as status-only rows; the OpenCode card loads its backend catalog on demand from the embedded runtime — its connections are install-wide, not per-user.
Defaults — the default assistant and per-provider model defaults, plus a “Your default” (just-me) assistant select.

Per-user model preferences (“Just me”)

When you’re logged in (a web identity resolves), the Model Tiers and Model Aliases panels show a “This install / Just me” scope toggle, and Defaults gains a “Your default” select. The “Just me” scope stores your personal tiers/aliases/default assistant in Archon’s database and applies them as the highest-precedence layer — your overrides win over the install config for runs and chats you start, without changing anyone else’s. This needs an identity but no TOKEN_ENCRYPTION_KEY (model names aren’t secrets); on a solo install without web auth the toggle simply doesn’t appear and everything behaves exactly as before.

If a chat asks for the large tier and only a different tier is configured, Archon uses the nearest preset and posts a one-line notice telling you which tier answered and where to set large.

Connecting from the CLI

The same actions are available headless via archon ai:

# Per-user credentials (need TOKEN_ENCRYPTION_KEY)
echo "$MY_KEY" | archon ai key set openrouter   # API key for any vendor
archon ai login anthropic                        # subscription (anthropic, openai, or github-copilot)
archon ai list                                   # what's connected

# Model tiers + aliases + default (ungated config — solo-OK)
archon ai tier set large claude opus
archon ai alias set @fast claude haiku
archon ai default claude

# The same, but just for YOU (per-user prefs; identity from ARCHON_USER_ID/$USER)
archon ai tier set large claude opus --scope user
archon ai default codex --scope user

The model-tier presets are the same ones you can hand-write in ~/.archon/config.yaml; see Configuration for the YAML format.

How Assistant Selection Works

Assistant type is set per codebase via the assistant field in .archon/config.yaml or the DEFAULT_AI_ASSISTANT env var
Once a conversation starts, the assistant type is locked for that conversation
DEFAULT_AI_ASSISTANT (optional) is used only for new conversations without codebase context
Workflows can override the assistant on a per-node basis with provider and model fields
Configuration priority: workflow-level options > config file defaults > SDK defaults

AI Assistants

Structured output guarantees

Claude Code

Install Claude Code

Binary path configuration (compiled binaries only)

Authentication Options

Option 1: Global Auth (Recommended)

Option 2: OAuth Token

Option 3: API Key (Pay-per-use)

Claude Configuration Options

Set as Default (Optional)

Codex

Install the Codex CLI

Binary path configuration (compiled binaries only)

Authenticate

Extract Credentials from Auth File

Set Environment Variables

Codex Configuration Options

Set as Default (Optional)

Skills

OpenCode (Community Provider)

Install

Authenticate

Configuration Options

Model reference format

Supported Archon Features

Usage in workflows

See also

Pi (Community Provider)

Install

Quick setup via wizard

Authenticate

Pi settings (baseline behavior)

Extensions (on by default)

Model reference format

Usage in workflows

Pi capabilities

See also

GitHub Copilot (Community Provider)

Install

Authenticate

Copilot Configuration Options

Supported Archon Features

Set as Default (Optional)

See also

Per-user credentials and AI Settings

When you need this

Enabling it

Connecting from the console

Per-user model preferences (“Just me”)

Connecting from the CLI

How Assistant Selection Works