.env.example

# Database (OPTIONAL)
# Default: SQLite at ~/.archon/archon.db (no setup required)
# Recommended: PostgreSQL for heavy parallel usage (20+ concurrent workflows)
#   docker compose --profile with-db up -d
# Uncomment for PostgreSQL:
# DATABASE_URL=postgresql://postgres:postgres@localhost:5432/remote_coding_agent

# AI Assistants
# Claude Auth Options:
# - CLAUDE_USE_GLOBAL_AUTH=true: Use global auth from `claude /login` (recommended)
# - CLAUDE_USE_GLOBAL_AUTH=false: Use explicit tokens below
# - Not set: Auto-detect (use tokens if present, otherwise global auth)
CLAUDE_USE_GLOBAL_AUTH=true
# CLAUDE_CODE_OAUTH_TOKEN=...
# CLAUDE_API_KEY=...

# Claude Code executable path (REQUIRED for compiled Archon binaries)
# Archon does not bundle Claude Code — install it separately and point us at it.
# Dev mode (`bun run`) auto-resolves via node_modules.
# Alternatively, set `assistants.claude.claudeBinaryPath` in ~/.archon/config.yaml.
#
# Install (Anthropic's recommended native installer):
#   macOS/Linux: curl -fsSL https://claude.ai/install.sh | bash
#   Windows:     irm https://claude.ai/install.ps1 | iex
#
# Then:
#   CLAUDE_BIN_PATH=$HOME/.local/bin/claude       (native installer)
#   CLAUDE_BIN_PATH=$(npm root -g)/@anthropic-ai/claude-code/cli.js  (npm alternative)
#   CLAUDE_BIN_PATH=$(npm root -g)/@anthropic-ai/claude-code-win32-x64  (Windows npm platform dir — auto-expanded to claude.exe)
# CLAUDE_BIN_PATH=

# Codex Authentication (get from ~/.codex/auth.json after running 'codex login')
# Required if using Codex as AI assistant
# On Linux/Mac: cat ~/.codex/auth.json
# On Windows: type %USERPROFILE%\.codex\auth.json
CODEX_ID_TOKEN=
CODEX_ACCESS_TOKEN=
CODEX_REFRESH_TOKEN=
CODEX_ACCOUNT_ID=
# CODEX_BIN_PATH=  # Optional: path to Codex native binary (binary builds only)

# GitHub Copilot (community provider — @github/copilot-sdk)
# Requires an active GitHub Copilot subscription. By default, Archon uses
# the credentials you configured via the Copilot CLI (`copilot login`).
# Generic GH_TOKEN / GITHUB_TOKEN (declared below) are intentionally NOT
# picked up — classic PATs lack Copilot entitlement and would fail. To
# opt back into env-token auth, set `useLoggedInUser: false` in
# `.archon/config.yaml`. Setting COPILOT_GITHUB_TOKEN is treated as
# explicit Copilot intent and always wins.
#
# COPILOT_GITHUB_TOKEN=        # Copilot-scoped PAT (always wins when set)
# COPILOT_BIN_PATH=            # Optional: path to Copilot CLI binary (binary builds only)

# Pi (community provider — @mariozechner/pi-coding-agent)
# One adapter, ~20 LLM backends. Archon's Pi adapter picks up credentials
# you've already configured via the Pi CLI (`pi /login` writes to
# ~/.pi/agent/auth.json), plus these env vars for backends you haven't
# logged into via OAuth. Env vars override auth.json per-request.
#
# Use by setting `provider: pi` and `model: <pi-provider-id>/<model-id>` in
# workflow YAML or `.archon/config.yaml` (e.g. model: google/gemini-2.5-pro).
#
# ANTHROPIC_API_KEY=           # Pi provider id: anthropic
# OPENAI_API_KEY=              # Pi provider id: openai
# GEMINI_API_KEY=              # Pi provider id: google
# GROQ_API_KEY=                # Pi provider id: groq
# MISTRAL_API_KEY=             # Pi provider id: mistral
# CEREBRAS_API_KEY=            # Pi provider id: cerebras
# XAI_API_KEY=                 # Pi provider id: xai
# OPENROUTER_API_KEY=          # Pi provider id: openrouter
# HUGGINGFACE_API_KEY=         # Pi provider id: huggingface
#
# Docker (optional): Pi data (auth, models, settings, sessions) lives in the
# container's ~/.pi/agent/ and is lost on rebuild. Set PI_CODING_AGENT_DIR to
# a path inside /.archon/ so it lands on the persisted volume. Must be set
# before the container starts (Pi reads it on each file path lookup).
# PI_CODING_AGENT_DIR=/.archon/pi

# Default AI Assistant (must match a registered provider, e.g. claude, codex, copilot, pi)
# Used for new conversations when no codebase specified — errors on unknown values
DEFAULT_AI_ASSISTANT=claude

# Title Generation Model (optional)
# Model used for generating conversation titles (lightweight task)
# When unset, uses the SDK's default model
# Examples: haiku, gpt-4o-mini, claude-haiku-4-5
# TITLE_GENERATION_MODEL=haiku

# ---- GitHub: choose ONE auth mode for the bot adapter ----
# Archon refuses to start if BOTH GITHUB_TOKEN and GITHUB_APP_ID are set.

# PAT mode (solo install, legacy). Bot comments post under this PAT's owner.
GH_TOKEN=
# Same as GH_TOKEN, used by the GitHub adapter in PAT mode.
GITHUB_TOKEN=

# App mode (multi-user, recommended for teams).
# See docs.archon.diy/adapters/github-app-setup for the full walkthrough.
# Required together:
# GITHUB_APP_ID=                      # numeric App ID from the GitHub App settings page
# GITHUB_APP_PRIVATE_KEY_PATH=        # absolute path to the App's .pem private key
# Inline alternative (newlines as literal \n inside double-quoted .env values):
# GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
# Optional:
# GITHUB_APP_SLUG=archon              # slug from the App URL; bot login = <slug>[bot]
#                                     # defaults to 'archon' — set this if you named your App differently
# GITHUB_APP_INSTALLATION_ID=         # set when single-install team; skips one HTTP call per repo
# ARCHON_ALLOW_INTERNAL_ON_PUBLIC_BIND=1
#                                     # OPT-IN ESCAPE HATCH for App mode + non-loopback bind. Only set
#                                     # when your reverse proxy already drops /internal/* AND the upstream
#                                     # genuinely needs a non-loopback bind. Default (unset): server
#                                     # refuses to start to prevent token leak. See github-app-setup.md.

# Per-user GitHub identity (device flow) — OPTIONAL, App mode only.
# The feature gate flips ON when the App is configured (GITHUB_APP_ID, set above)
# AND TOKEN_ENCRYPTION_KEY is present — that enables the `requires: [github]` gate
# and the unconnected-user token scrub. GITHUB_APP_CLIENT_ID is ALSO required so
# teammates can actually connect (Slack `/archon connect github`, CLI
# `archon auth github`, or the Web UI Settings page) — set all three. PR comments,
# commits, and pushes then attribute to the human; workflows declaring
# `requires: [github]` hard-block unconnected users. Without TOKEN_ENCRYPTION_KEY,
# App mode still works as the bot.
# GITHUB_APP_CLIENT_ID=               # the App "Client ID" (starts with Iv1./Iv23), NOT the numeric App ID
# TOKEN_ENCRYPTION_KEY=               # 64-hex (32 bytes). Generate: openssl rand -hex 32
#                                     # ROTATING THIS invalidates all stored user tokens (they must reconnect).
# ARCHON_ALLOW_ORG_GITHUB_TOKEN_FALLBACK=
#                                     # default false. When false, a workflow run by an UNCONNECTED user
#                                     # has GH_TOKEN/GITHUB_TOKEN scrubbed (gh/git fail) rather than
#                                     # silently using the shared org/bot token. Set true to opt back in.

# Interim Web UI auth (OPTIONAL) — trust a reverse-proxy-set header.
# A reverse proxy (e.g. Caddy basicauth) authenticates and sets this header to
# an opaque username; Archon trusts it and attributes web rows to that user.
# SECURITY: only safe when Archon is reachable solely via the proxy (bind
# 127.0.0.1). Absent header → web rows stay unattributed (never elevated).
# ARCHON_WEB_AUTH_HEADER=X-Archon-User   # header name the proxy sets (default shown)

# Web UI login (OPTIONAL, Postgres-only) — real per-user email/password login
# via Better Auth, mounted at /api/auth/*. OPT-IN: enabled only when BOTH
# DATABASE_URL (Postgres) and BETTER_AUTH_SECRET are set. SQLite/solo installs
# can never enable it and are completely unchanged. Supersedes the auth-service
# sidecar below; the X-Archon-User header above remains a fallback for proxy
# deploys. A Better Auth session maps to the canonical Archon user; everyone is
# 'admin' for now and visibility stays open (?mine is an opt-in filter, not a
# boundary).
# BETTER_AUTH_SECRET=                    # >=32 chars. Generate: openssl rand -base64 32
# BETTER_AUTH_URL=                       # optional; set only behind a fixed-origin proxy (else inferred)
# BETTER_AUTH_TRUSTED_ORIGINS=           # optional; comma-separated extra origins for CSRF
# ARCHON_AUTH_ALLOWED_EMAILS=            # invite allowlist (comma-separated). Set this to gate signup.
# ARCHON_AUTH_OPEN_SIGNUP=               # 'true' = open public signup. Default (unset) + no allowlist
#                                        #   = signup DISABLED (login only) — never silently open.
# ARCHON_WEB_AUTH_REQUIRED=              # default ON when web auth is enabled: every /api/* request
#                                        #   needs a session/identity (401 otherwise) except /api/auth/*
#                                        #   and /api/health*. This makes Better Auth the real access
#                                        #   gate so you can drop the Caddy forward_auth sidecar. Set
#                                        #   'false' to keep login-UI-only (e.g. a proxy already gates).

# GitHub Webhooks (required for both PAT and App modes)
WEBHOOK_SECRET=

# GitHub User Whitelist (optional - comma-separated usernames)
# When set, only listed GitHub users can trigger webhook processing
# When empty/unset, webhooks are processed for all users
# Usernames are case-insensitive (octocat == Octocat)
GITHUB_ALLOWED_USERS=

# GitLab Webhooks (Community Forge Adapter)
# GITLAB_URL=https://gitlab.com  # Or self-hosted: https://gitlab.example.com
GITLAB_TOKEN=  # Personal/Project Access Token with 'api' scope
GITLAB_WEBHOOK_SECRET=  # Secret token set in GitLab webhook configuration
# GITLAB_ALLOWED_USERS=  # Optional: comma-separated GitLab usernames
# GITLAB_BOT_MENTION=archon  # Optional: @mention name for detection (default: BOT_DISPLAY_NAME)

# Platforms - set the tokens for the ones you want to use
# Telegram - <get token from @BotFather>
TELEGRAM_BOT_TOKEN=
# Discord - <get token from Discord Developer Portal>
DISCORD_BOT_TOKEN=

# Slack Bot (Socket Mode)
# Create app at https://api.slack.com/apps - see docs/slack-setup.md
SLACK_BOT_TOKEN=
SLACK_APP_TOKEN=

# Slack User Whitelist (optional - comma-separated user IDs)
# When set, only listed Slack users can interact with the bot
# When empty/unset, bot responds to all users
# Get user IDs: Slack profile > ... > Copy member ID
SLACK_ALLOWED_USER_IDS=

# Discord User Whitelist (optional - comma-separated user IDs)
# When set, only listed Discord users can interact with the bot
# When empty/unset, bot responds to all users
# Get user IDs in Discord: Settings > Advanced > Developer Mode, then right-click user > Copy ID
DISCORD_ALLOWED_USER_IDS=

# Telegram User Whitelist (optional - comma-separated user IDs)
# When set, only listed Telegram users can interact with the bot
# When empty/unset, bot responds to all users
# Get your user ID by messaging @userinfobot on Telegram
TELEGRAM_ALLOWED_USER_IDS=

# Platform Streaming Mode (stream | batch)
TELEGRAM_STREAMING_MODE=stream  # stream (default) | batch
DISCORD_STREAMING_MODE=batch    # batch (default) | stream
SLACK_STREAMING_MODE=batch      # batch (default) | stream

# Bot Display Name (shown in batch mode "starting" message)
# Default: Archon
# BOT_DISPLAY_NAME=Archon

# GitHub Bot Mention (optional - for @mention detection in GitHub issues/PRs)
# When set, the bot will respond to this @mention in issues/PRs
# If not set, falls back to BOT_DISPLAY_NAME
# GITHUB_BOT_MENTION=archon

# ============================================
# Gitea (Community Forge Adapter)
# ============================================
# Self-hosted Gitea instance URL
GITEA_URL=  # e.g. https://gitea.example.com

# Gitea Token (for API access and authenticated clones)
GITEA_TOKEN=  # Personal access token or bot account token

# Gitea Webhook Secret (set this in your Gitea webhook configuration)
GITEA_WEBHOOK_SECRET=

# Gitea User Whitelist (optional - comma-separated usernames)
# When set, only listed Gitea users can trigger webhook processing
# When not set, all users can trigger (open access mode)
GITEA_ALLOWED_USERS=

# Gitea Bot Mention (optional - for @mention detection in Gitea issues/PRs)
# If not set, falls back to BOT_DISPLAY_NAME then config.botName
# GITEA_BOT_MENTION=archon

# Server
# PORT=3090  # Default: 3090. Uncomment to override — must match between server and Vite proxy.
# HOST=0.0.0.0  # Bind address (default: 0.0.0.0). Set to 127.0.0.1 to restrict to localhost only.

# Cloud Deployment (for --profile cloud with Caddy reverse proxy)
# Set your domain and point DNS to your server — Caddy handles TLS automatically
# DOMAIN=archon.example.com

# Basic Auth (optional) — protects the Web UI and API when exposed to the internet
# Leave empty to disable (e.g. when using IP-based firewall rules instead).
# To enable:
#   1. Generate hash: docker run caddy caddy hash-password --plaintext 'YOUR_PASSWORD'
#   2. Set the variable below (replace admin and the hash):
# CADDY_BASIC_AUTH=basicauth @protected { admin $$2a$$14$$REPLACE_WITH_HASH }

# Form Auth (optional) — HTML login page via Caddy forward_auth + auth-service
# Alternative to CADDY_BASIC_AUTH. Requires: --profile auth in docker compose.
# To enable:
#   1. Generate bcrypt hash (requires auth-service container):
#      docker compose --profile auth run --rm auth-service node -e \
#        "require('bcryptjs').hash('YOUR_PASSWORD', 12).then(h => console.log(h))"
#   2. Generate a random cookie secret:
#      docker run --rm node:22-alpine node -e \
#        "console.log(require('crypto').randomBytes(32).toString('hex'))"
#   3. Set the variables below and uncomment Option A in Caddyfile
# AUTH_USERNAME=admin
# AUTH_PASSWORD_HASH=$$2b$$12$$REPLACE_WITH_BCRYPT_HASH
#   ⚠ Escape every $ as $$ — Docker Compose interprets $ as variable substitution
# COOKIE_SECRET=REPLACE_WITH_64_HEX_CHARS
# AUTH_SERVICE_PORT=9000
# COOKIE_MAX_AGE=86400

# ============================================
# Archon Directory Configuration
# ============================================
# All Archon-managed files go in ~/.archon/ by default
# Override with ARCHON_HOME to use a custom location.
# Docker: IGNORED. The container always uses /.archon regardless of this value
# (the variable still leaks into the container env via env_file but has no effect).
# ARCHON_HOME=~/.archon

# Docker data directory (host path where Archon stores workspaces, worktrees, artifacts, etc.)
# Default: Docker-managed volume (archon_data)
# Set to an absolute path on the host for full control over data location:
# Docker: host-only. Used by docker-compose to choose the bind-mount source for /.archon.
# NOT read by Archon source code — the container always sees data at /.archon.
# ARCHON_DATA=/opt/archon-data

# Docker user-home directory (host path for /home/appuser inside the container).
# /home/appuser is persisted by default so Claude Code skills/commands/agents/hooks,
# Codex/Pi auth state, ~/.gitconfig, and shell history survive container rebuilds.
# Default: Docker-managed volume (archon_user_home)
# Set to an absolute path on the host to bind-mount instead (must be writable by UID 1001):
# Docker: host-only. Used by docker-compose to choose the bind-mount source for /home/appuser.
# NOT read by Archon source code.
# ARCHON_USER_HOME=/opt/archon-user-home

# Logging (optional)
# Set log level: fatal | error | warn | info | debug | trace
# Default: info
# CLI can override with --quiet (warn) or --verbose (debug)
# LOG_LEVEL=info

# Concurrency
MAX_CONCURRENT_CONVERSATIONS=10  # Maximum concurrent AI conversations (default: 10)

# Session Retention
# SESSION_RETENTION_DAYS=30  # Delete inactive sessions older than N days (default: 30)

# Anonymous Telemetry (optional)
# Archon sends a few anonymous events to PostHog (archon_started, workflow_invoked,
# workflow_completed/failed) so maintainers can see active installs, which workflows
# get real usage, and whether runs succeed. No PII — categorical only: workflow name
# (real for bundled, "custom" for your own), platform, provider/model, node shape,
# run outcome/duration, OS/arch/version, and a random install UUID. No identities,
# no prompts, no paths, no descriptions, no code, no IP, no geo, no error text.
# See README "Telemetry" for the full list.
#
# Opt out (any one disables telemetry):
#   ARCHON_TELEMETRY_DISABLED=1
#   DO_NOT_TRACK=1                          (de facto standard)
#   POSTHOG_API_KEY=off                     (off | 0 | false | disabled | "")
#   CI=true                                 (auto-disabled in CI environments)
#
# Inspect or rotate the install UUID:
#   archon telemetry status
#   archon telemetry reset
#
# Point at a self-hosted PostHog or a different project:
#   POSTHOG_API_KEY=phc_yourKeyHere
#   POSTHOG_HOST=https://eu.i.posthog.com   (default: https://us.i.posthog.com)