Skip to content

Configuration

Set these in your shell, ~/.archon/.env for user-wide settings, or <cwd>/.archon/.env for project overrides. The CLI strips keys named in a target repository’s <cwd>/.env; use the Archon-owned files for credentials. See environment file locations and load order, including the source-server exception.

VariableRequiredDescription
CLAUDE_BIN_PATHNo (binary builds autodetect ~/.local/bin/claude)Absolute path to the Claude Code binary, SDK cli.js, or the npm platform-package directory (e.g. @anthropic-ai/claude-code-win32-x64, auto-expanded to claude/claude.exe). Takes precedence over assistants.claude.claudeBinaryPath in both source and compiled installs. Without either pin, compiled builds autodetect the native-installer path; dev mode (bun run) lets the SDK resolve via node_modules. Invalid explicit pins fail in either mode.
CLAUDE_USE_GLOBAL_AUTHNoStartup-check marker for a claude /login session; Claude Code never reads it. Set automatically when no other Claude token is set. A Docker container has no login session, so set a token or key there.
CLAUDE_CODE_OAUTH_TOKENNoOAuth token from claude setup-token
CLAUDE_API_KEYNoAnthropic API key for pay-per-use
CODEX_BIN_PATHNoAbsolute path to the Codex CLI binary. Overrides auto-detection in compiled Archon builds.
ARCHON_CODEX_ACCESS_TOKENNoDocker only: one of four copied Codex login values the container writes to ~/.codex/auth.json. Elsewhere use codex login or CODEX_API_KEY (see AI Assistants)
DATABASE_URLNoPostgreSQL connection string (default: SQLite)
GH_TOKENNoGitHub personal access token — used to authenticate when cloning private repos from github.com or the GITHUB_URL host
GITHUB_URLNoGitHub Enterprise Server base URL (e.g. https://github.example.com); unset means github.com. See GitHub Enterprise Server
GITLAB_TOKENNoGitLab personal/project access token — used to authenticate when cloning private repos from gitlab.com or the GITLAB_URL host (also used by the GitLab adapter)
GITEA_TOKENNoGitea/Forgejo access token — used to authenticate when cloning private repos from gitea.com or the GITEA_URL / FORGEJO_URL host (also used by the Gitea adapter)
LOG_LEVELNodebug, info (default for the server and archon serve), warn (default for other CLI commands), error. See CLI logs.
PORTNoServer port (default: 3090, Docker: 3000)
WSL_DISTRO_NAMENo (WSL sets it automatically)WSL distro name; Archon reads it to emit Windows-host-friendly vscode://vscode-remote/wsl+<distro>/... “Open in IDE” links. Override only to force a specific distro name into the URI.

Create .archon/config.yaml in your repository:

assistants:
claude:
model: sonnet # or 'opus', 'haiku', 'inherit'
settingSources:
- project
codex:
model: gpt-5.6-sol
modelReasoningEffort: medium
# docs:
# path: packages/docs-web/src/content/docs # Optional: default is docs/

See the full configuration reference for all options.