### Start Interactive Setup Wizard

Source: https://archon.diy/reference/cli

Launch the interactive setup wizard for configuring credentials and other settings. This command guides the user through the initial setup process.

```bash
archon setup
```

--------------------------------

### Local Development Setup with Bun

Source: https://archon.diy/deployment/local

Clone the repository, install dependencies, configure environment variables, and start the development server. This setup uses SQLite by default and requires Bun 1.0+.

```bash
git clone https://github.com/coleam00/Archon
cd Archon
bun install

cp .env.example .env
nano .env  # Add your AI assistant tokens (Claude or Codex)

bun run dev
```

--------------------------------

### Download and Run Pre-built Archon Image

Source: https://archon.diy/deployment/docker

Use these commands to download the Docker Compose file and environment example, set up your environment, and start Archon using the pre-built image. Ensure you edit the .env file with your specific configurations.

```bash
mkdir archon && cd archon
curl -O https://raw.githubusercontent.com/coleam00/Archon/main/deploy/docker-compose.yml
curl -O https://raw.githubusercontent.com/coleam00/Archon/main/.env.example

cp .env.example .env
# Edit .env — set AI credentials, DOMAIN, etc.


docker compose up -d
```

--------------------------------

### Install and authenticate glab CLI

Source: https://archon.diy/adapters/community/gitlab

Initial setup commands to install the tool via Homebrew and authenticate with a GitLab instance.

```bash
brew install glab
glab auth login
```

--------------------------------

### Post-Boot Server Configuration

Source: https://archon.diy/deployment/docker

Commands to verify the setup, configure environment variables, and start the Archon services on a remote server.

```bash
# Check setup completed
cat /opt/archon/SETUP_COMPLETE


# Edit credentials and domain
nano /opt/archon/.env


# Set at minimum:
#   CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
#   DOMAIN=archon.example.com
#   DATABASE_URL=postgresql://postgres:postgres@postgres:5432/remote_coding_agent


# (Optional) Set up basic auth to protect Web UI:
# docker run caddy caddy hash-password --plaintext 'YOUR_PASSWORD'
# Add to .env: CADDY_BASIC_AUTH=basicauth @protected { admin $$2a$$14$$<hash> }


# Start
cd /opt/archon
docker compose --profile with-db --profile cloud up -d
```

--------------------------------

### Build and Start Production

Source: https://archon.diy/adapters/web

Compiles the frontend into static files and starts the integrated server on port 3090.

```bash
bun run build    # Build the frontend into static files
bun run start    # Server serves both API and Web UI on port 3090
```

--------------------------------

### Install and Setup Claude OAuth Token

Source: https://archon.diy/getting-started/ai-assistants

Install the Claude Code CLI and run `claude setup-token` to obtain an OAuth token. This token should then be set as the CLAUDE_CODE_OAUTH_TOKEN environment variable.

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

```bash
CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-xxxxx
```

--------------------------------

### Start Services with Remote PostgreSQL

Source: https://archon.diy/deployment/cloud

Starts the application and Caddy reverse proxy using Docker Compose with the 'cloud' profile, suitable for remote PostgreSQL setups. Includes building the image if necessary.

```bash
docker compose --profile cloud up -d --build
```

--------------------------------

### Install from Private Repository

Source: https://archon.diy/contributing/releasing

Alternative installation method using the GitHub CLI for private repositories.

```bash
# Download and install using gh (requires GitHub authentication)
gh release download v0.2.0 --repo coleam00/Archon \
  --pattern "archon-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/x64/;s/aarch64/arm64/')" \
  --dir /tmp/archon-install

# Install the binary
chmod +x /tmp/archon-install/archon-*
sudo mv /tmp/archon-install/archon-* /usr/local/bin/archon

# Verify
archon version
```

--------------------------------

### Install Archon CLI

Source: https://archon.diy/book/first-five-minutes

Clone the Archon repository, install dependencies using Bun, and then link the CLI globally. Verify the installation by checking the version.

```bash
# Clone and install
git clone https://github.com/coleam00/Archon.git
cd Archon
bun install


# Register the archon command globally
cd packages/cli && bun link && cd ../..


# Verify it worked
archon version
```

--------------------------------

### Apply Database Migrations in Local PostgreSQL Docker Setup

Source: https://archon.diy/deployment/local

Connects to the running PostgreSQL container and applies database migrations. Use '\i /migrations/000_combined.sql' for a fresh install or apply individual migration files.

```bash
# Connect to the running postgres container
docker compose exec postgres psql -U postgres -d remote_coding_agent

# For a fresh install, run the combined migration (idempotent, creates all 7 tables):
\i /migrations/000_combined.sql

# Or apply individual migrations you haven't applied yet.
# Check the migrations/ directory for the full list (currently 001 through 019).
\q
```

--------------------------------

### Open Setup Wizard in New Terminal

Source: https://archon.diy/reference/cli

Initiate the Archon setup wizard in a separate terminal window. This flag is useful for a less intrusive setup experience.

```bash
archon setup --spawn
```

--------------------------------

### Install Docker Compose, Git, and PostgreSQL Client

Source: https://archon.diy/deployment/cloud

Update the package list and install Docker Compose, Git, and the PostgreSQL client. Verify that these installations were successful.

```bash
# Update package list
sudo apt update

# Install required packages
sudo apt install -y docker-compose-plugin git postgresql-client

# Verify installations
docker --version
docker compose version
git --version
psql --version
```

--------------------------------

### Initialize Environment File

Source: https://archon.diy/deployment/cloud

Commands to create the .env file from the example template.

```bash
# Copy example file
cp .env.example .env


# Edit with nano
nano .env
```

--------------------------------

### Install and Open agent-browser

Source: https://archon.diy/reference/troubleshooting

Install the `agent-browser` globally and then open it, potentially to a specific Archon instance URL.

```bash
npm install -g agent-browser
agent-browser install
```

--------------------------------

### Prompting Examples

Source: https://archon.diy/guides/remotion-workflow

Examples of effective and ineffective prompts for the generation workflow.

```bash
# Good — describes what to see
bun run cli workflow run archon-remotion-generate "A 10-second animated bar chart showing monthly revenue growing from $10K to $100K, with each bar sliding up with a spring animation"


# Good — specific visual style
bun run cli workflow run archon-remotion-generate "Dark background, white text. Three slides: title card with company name, bullet points sliding in one by one, closing CTA with a pulse animation"


# Less good — too vague
bun run cli workflow run archon-remotion-generate "make a video"
```

--------------------------------

### Start Development Environment

Source: https://archon.diy/adapters/web

Launches both the backend and frontend with hot reloading enabled.

```bash
# Start both backend + frontend with hot reload
bun run dev
# Web UI: http://localhost:5173
# API server: http://localhost:3090
```

--------------------------------

### Docker Setup with Local PostgreSQL

Source: https://archon.diy/deployment/local

Starts both the Archon application and a PostgreSQL database in Docker containers. The database schema is created automatically on first startup.

```bash
# 1. Configure .env
# 2. Start both containers
docker compose --profile with-db up -d --build

# 3. Wait for startup (watch logs)
docker compose logs -f app

# 4. Verify
curl http://localhost:3000/api/health
```

--------------------------------

### Manual Docker Installation

Source: https://archon.diy/deployment/docker

Commands to install Docker on Ubuntu/Debian and verify the installation.

```bash
# On Ubuntu/Debian
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER


# Log out and back in for group change to take effect
exit
# ssh back in


# Verify
docker --version
docker compose version
```

--------------------------------

### Archon Configuration Example

Source: https://archon.diy/getting-started/overview

Example configuration file for defining the AI assistant, command paths, and file copying rules for worktrees.

```yaml
assistant: claude
commands:
  folder: .claude/commands/archon    # additional command search path
worktree:
  copyFiles:
    - .env.example                   # copy into worktrees (same filename)
    - .env
```

--------------------------------

### Build and Start Local Production Server

Source: https://archon.diy/deployment/local

Builds the frontend for production and then starts the backend server which serves both the API and the Web UI. The server runs on port 3090.

```bash
bun run build
bun run start
```

--------------------------------

### Install Dependencies with Bun

Source: https://archon.diy/getting-started/overview

Install all project dependencies using Bun. This command should be run after cloning the repository.

```bash
bun install
```

--------------------------------

### Start services with profiles

Source: https://archon.diy/deployment/docker

Command to launch the application with the necessary database, cloud, and authentication profiles.

```bash
docker compose --profile with-db --profile cloud --profile auth up -d
```

--------------------------------

### Install skills from GitHub

Source: https://archon.diy/guides/skills

Commands to install skills directly from public or private GitHub repositories.

```bash
# Public repo
npx skills add owner/repo


# Specific path in repo
npx skills add owner/repo/path/to/skill


# Private repo (uses SSH keys or GITHUB_TOKEN)
npx skills add git@github.com:org/private-skills.git
```

--------------------------------

### Copy Caddyfile Example

Source: https://archon.diy/deployment/cloud

Copies the example Caddyfile to be used for configuration. No manual editing is required for this step.

```bash
cp Caddyfile.example Caddyfile
```

--------------------------------

### Start Archon Services

Source: https://archon.diy/deployment/docker

Launch the application with PostgreSQL and Caddy profiles enabled.

```bash
docker compose --profile with-db --profile cloud up -d
```

--------------------------------

### Initialize a Remotion Project

Source: https://archon.diy/guides/remotion-workflow

Sets up a new Remotion project directory and installs necessary dependencies.

```bash
npx create-video@latest my-video
cd my-video
npm install
```

--------------------------------

### Install Dependencies

Source: https://archon.diy/getting-started/overview

Install project dependencies using Bun. If issues persist, delete `node_modules` and reinstall.

```bash
bun install
```

```bash
bun install
```

--------------------------------

### Verify Release Installation

Source: https://archon.diy/contributing/releasing

Commands to test the installation script and verify the installed version.

```bash
# Test the install script (only works if repo is public)
curl -fsSL https://raw.githubusercontent.com/coleam00/Archon/main/scripts/install.sh | bash


# Verify version
archon version
```

--------------------------------

### Docker Setup with Remote PostgreSQL

Source: https://archon.diy/deployment/local

Sets up the Archon application container to connect to an external PostgreSQL database. This involves downloading deployment files, configuring the .env file, and starting the app container.

```bash
mkdir archon && cd archon
curl -fsSL https://raw.githubusercontent.com/coleam00/Archon/main/deploy/docker-compose.yml -o docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/coleam00/Archon/main/deploy/.env.example -o .env

nano .env

docker compose up -d
```

--------------------------------

### Copy Environment Example File

Source: https://archon.diy/getting-started/overview

Create a .env file from the .env.example template. This is required for Web UI/server mode.

```bash
cp .env.example .env
```

--------------------------------

### Install WSL2

Source: https://archon.diy/deployment/windows

Run this command to install the Windows Subsystem for Linux version 2. Restart your computer after installation.

```bash
wsl --install
```

--------------------------------

### Clone and Install Archon

Source: https://archon.diy/deployment/windows

Clones the Archon repository, navigates into the directory, and installs its dependencies using Bun.

```bash
git clone https://github.com/coleam00/Archon
cd Archon
bun install
```

--------------------------------

### Trace Error Path Example

Source: https://archon.diy/guides/authoring-commands

Example of how to document an error path.

```bash
grep -r "ErrorType" src/
```

```bash
cat src/handlers/error.ts
```

--------------------------------

### Install Docker

Source: https://archon.diy/deployment/cloud

Install Docker on your server using the official installation script. Add your deployment user to the 'docker' group to allow running Docker commands without sudo. Log out and back in for group changes to take effect.

```bash
# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add deploy user to docker group
sudo usermod -aG docker deploy

# Log out and back in for group changes to take effect
exit
ssh -i ~/.ssh/id_ed25519 deploy@your-server-ip
```

--------------------------------

### Start Individual Services

Source: https://archon.diy/adapters/web

Launches the backend API server or the frontend development server independently.

```bash
# Backend API server only (port 3090)
bun run dev:server


# Frontend dev server only (port 5173, requires backend running)
bun run dev:web
```

--------------------------------

### Install agent-browser globally

Source: https://archon.diy/deployment/e2e-testing

Commands to install the agent-browser package and download the required browser engine.

```bash
# Install globally
npm install -g agent-browser


# Download browser engine (Chrome for Testing)
agent-browser install
```

--------------------------------

### Full workflow example with multiple hooks

Source: https://archon.diy/guides/hooks

An example of a full workflow demonstrating the use of PreToolUse and PostToolUse hooks to enforce security and provide context during a code review process.

```yaml
name: safe-code-review
description: Review code with guardrails
nodes:
  - id: fetch-diff
    bash: "git diff main...HEAD"


  - id: review
    prompt: "Review this diff for bugs and security issues: $fetch-diff.output"
    depends_on: [fetch-diff]
    hooks:
      PreToolUse:
        - matcher: "Bash"
          response:
            hookSpecificOutput:
              hookEventName: PreToolUse
              permissionDecision: deny
              permissionDecisionReason: "Code review should not execute commands"
        - matcher: "Write|Edit"
          response:
            hookSpecificOutput:
              hookEventName: PreToolUse
              permissionDecision: deny
              permissionDecisionReason: "Code review is read-only"
      PostToolUse:
        - matcher: "Read"
          response:
            hookSpecificOutput:
              hookEventName: PostToolUse
              additionalContext: "Focus on security issues in this file"


  - id: summarize
    prompt: "Summarize the review findings from $review.output"
    depends_on: [review]
    allowed_tools: []
```

--------------------------------

### Install Archon via Homebrew (macOS/Linux)

Source: https://archon.diy/getting-started/installation

Install Archon using Homebrew on macOS or Linux. This command adds the Archon tap and installs the package.

```bash
brew install coleam00/archon/archon
```

--------------------------------

### Run Development Server

Source: https://archon.diy/getting-started/overview

Commands to start the development server for the entire project, backend only, or frontend only.

```bash
bun run dev
```

```bash
bun run dev:server
```

```bash
bun run dev:web
```

--------------------------------

### Codex Setup

Source: https://archon.diy/deployment/cloud

Commands to authenticate and configure Codex credentials.

```bash
# Install Codex CLI (if not already installed)
# Visit: https://docs.codex.com/installation


# Authenticate
codex login


# Extract credentials
cat ~/.codex/auth.json
# On Windows: type %USERPROFILE%\.codex\auth.json


# Copy all four values
```

```bash
nano .env
```

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

```bash
DEFAULT_AI_ASSISTANT=codex
```

--------------------------------

### Start Services with Local PostgreSQL

Source: https://archon.diy/deployment/cloud

Starts the application, PostgreSQL, and Caddy using Docker Compose with both 'with-db' and 'cloud' profiles for local PostgreSQL development. Includes building the image.

```bash
docker compose --profile with-db --profile cloud up -d --build
```

--------------------------------

### Verify agent-browser installation

Source: https://archon.diy/deployment/e2e-testing

Commands to check the installed version and perform a basic smoke test by opening and closing a URL.

```bash
agent-browser --version
# Expected: prints version number (e.g., 0.x.x)


# Quick smoke test — opens a page and closes
agent-browser open https://example.com
agent-browser close
```

--------------------------------

### Workflow File Structure Example

Source: https://archon.diy/guides/authoring-workflows

Illustrates the directory structure for storing workflow files.

```tree
.archon/
├── workflows/
│   ├── my-workflow.yaml
│   └── review/
│       └── full-review.yaml    # Subdirectories work
└── commands/
    └── [commands used by workflows]
```

--------------------------------

### Start Local Development Server

Source: https://archon.diy/deployment/local

Starts the backend API and the React frontend development server simultaneously. The API server runs on port 3090 and the Web UI on port 5173.

```bash
bun run dev
```

--------------------------------

### Install Bun in WSL2

Source: https://archon.diy/deployment/windows

Installs Bun using the official script and sources the bashrc file to make Bun available in the current session.

```bash
curl -fsSL https://bun.sh/install | bash
source ~/.bashrc
```

--------------------------------

### Manage skills via CLI

Source: https://archon.diy/guides/skills

Various commands for installing, searching, and managing skills.

```bash
# Install to current project
npx skills add remotion-dev/skills


# Install globally (all projects)
npx skills add remotion-dev/skills -g


# Install a specific skill from a multi-skill repo
npx skills add anthropics/skills --skill skill-creator


# Search for skills
npx skills find "database"
```

--------------------------------

### Start PostgreSQL with Docker for Local Development

Source: https://archon.diy/deployment/local

Starts a PostgreSQL container using Docker Compose for local development. This command should be used if you prefer PostgreSQL over SQLite.

```bash
docker compose --profile with-db up -d postgres
# Set DATABASE_URL=postgresql://postgres:postgres@localhost:5432/remote_coding_agent in .env
```

--------------------------------

### Install Archon CLI Globally

Source: https://archon.diy/getting-started/overview

Steps to link the CLI package and ensure the binary is in the system PATH.

```bash
cd packages/cli && bun link && cd ../..
```

```bash
# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

```bash
archon version
```

--------------------------------

### Install Archon via PowerShell (Windows)

Source: https://archon.diy/getting-started/installation

Execute this command in PowerShell to install Archon on Windows. Ensure internet access and PowerShell execution policy allows script execution.

```powershell
irm https://archon.diy/install.ps1 | iex
```

--------------------------------

### Install Remotion Skills

Source: https://archon.diy/guides/remotion-workflow

Adds the remotion-dev/skills package to provide the agent with best-practice guidelines for video generation.

```bash
npx skills add remotion-dev/skills
```

--------------------------------

### Configure Archon YAML Settings

Source: https://archon.diy/reference/configuration

Example configuration for command folder detection and AI assistant preferences.

```yaml
commands:
  folder: .claude/commands/archon  # Additional folder to search
  autoLoad: true
```

```yaml
defaultAssistant: codex
```

--------------------------------

### PostToolUse Hook Example

Source: https://archon.diy/book/hooks-and-quality

Inject context after a tool completes to guide the model's subsequent processing.

```yaml

PostToolUse:
  - matcher: "Read"
    response:
      hookSpecificOutput:
        hookEventName: PostToolUse
        additionalContext: "You just read this file. Do not modify it — analysis only."
```

--------------------------------

### Claude SDK: Override System Prompt

Source: https://archon.diy/guides/authoring-workflows

Customize the system prompt for a Claude node to guide its behavior, for example, to specialize as a security expert.

```yaml
- id: security-review
  prompt: "Review this code for vulnerabilities"
  systemPrompt: "You are a security expert specializing in TypeScript. Focus only on security issues."
```

--------------------------------

### Start Archon Web UI Server

Source: https://archon.diy/getting-started/overview

Commands to launch the development server. Use the host flag to expose the Web UI on a network.

```bash
bun run dev
```

```bash
bun run dev:web -- --host 0.0.0.0
```

--------------------------------

### Troubleshoot daemon on macOS/Linux

Source: https://archon.diy/deployment/e2e-testing

Command sequence to resolve issues where the agent-browser daemon fails to start.

```bash
# Kill stale daemons and retry
pkill -f daemon.js
agent-browser open http://localhost:3090
```

--------------------------------

### Local Docker Desktop Quick Start

Source: https://archon.diy/deployment/docker

Commands to clone the repository and launch the Archon service locally using SQLite.

```bash
git clone https://github.com/coleam00/Archon.git
cd Archon
cp .env.example .env
# Edit .env: set CLAUDE_CODE_OAUTH_TOKEN or CLAUDE_API_KEY
docker compose up -d
```

--------------------------------

### Configure Cloudflare DNS A Record

Source: https://archon.diy/deployment/cloud

Example settings for pointing a domain to the server IP via Cloudflare.

```text
Type: A
Name: archon
Content: 123.45.67.89
Proxy: Off (DNS Only)
TTL: Auto
```

--------------------------------

### Verify Archon Installation

Source: https://archon.diy/deployment/windows

Checks the installed Archon version to confirm successful installation.

```bash
archon version
```

--------------------------------

### Authenticate with Codex CLI

Source: https://archon.diy/getting-started/ai-assistants

Install the Codex CLI and run `codex login` to initiate the browser-based authentication flow.

```bash
# Install Codex CLI first: https://docs.codex.com/installation
codex login

# Follow browser authentication flow
```

--------------------------------

### Install Archon via curl (macOS/Linux)

Source: https://archon.diy/getting-started/installation

Use this command to quickly install Archon on macOS or Linux systems. Ensure curl is installed.

```bash
curl -fsSL https://archon.diy/install | bash
```

--------------------------------

### Start development servers on Windows

Source: https://archon.diy/deployment/e2e-testing-wsl

Commands to launch backend and frontend servers on Windows, ensuring they bind to all interfaces for WSL access.

```bash
# Backend (Hono on port 3090) - already binds to 0.0.0.0 by default
bun run dev:server &


# Frontend (Vite on port 5173) - needs --host flag
cd packages/web && bun x vite --host 0.0.0.0 &
```

--------------------------------

### Monitor Application Startup Logs

Source: https://archon.diy/deployment/cloud

Monitors the application logs to confirm successful startup. Use the '--profile with-db' flag if using local PostgreSQL. Look for specific readiness messages.

```bash
# Watch logs for successful startup (use --profile with-db for local PostgreSQL)
docker compose --profile cloud logs -f app

# Look for:
# [App] Starting Archon
# [Database] Connected successfully
# [App] Archon is ready!
```

--------------------------------

### Build Archon Docker Image and Run

Source: https://archon.diy/deployment/docker

Build the Archon Docker image from source and run it. This process involves building the image and then starting a container, mapping the host's port 3000 to the container's port 3000. The image includes Bun, system dependencies, and Archon application files.

```bash
docker build -t archon .
docker run --env-file .env -p 3000:3000 archon
```

--------------------------------

### Create a pre-release tag

Source: https://archon.diy/contributing/releasing

Use this sequence to tag and push a beta version for testing prior to a public release.

```bash
# Create a pre-release tag
git tag v0.3.0-beta.1
git push origin v0.3.0-beta.1
```

--------------------------------

### Example Validation Error Message

Source: https://archon.diy/guides/authoring-workflows

This is an example of a model compatibility error message that may appear during workflow validation.

```text
Model "sonnet" is not compatible with provider "codex"
```

--------------------------------

### List Installed Skills

Source: https://archon.diy/guides/skills

Verify that skills are installed correctly on your system using this command. This helps in troubleshooting 'No validation' issues.

```bash
npx skills list

```

--------------------------------

### Command File Structure Example

Source: https://archon.diy/book/first-command

This is the complete structure of a command file, including frontmatter for metadata and the AI instructions body. Variables like $ARGUMENTS are substituted before execution.

```markdown
---
description: Run tests for a specific module and report results    <- shown in /commands list
argument-hint: <module-name>                                        <- tells users what to pass
---


# Run Tests


**Input**: $ARGUMENTS                                              <- always show your input


---


## Your Task


Run the tests for the `$ARGUMENTS` module and report what you find.


[... AI instructions ...]

```

--------------------------------

### Stop Local PostgreSQL Docker Setup

Source: https://archon.diy/deployment/local

Stops and removes the application and PostgreSQL Docker containers when using the local PostgreSQL setup.

```bash
docker compose --profile with-db down
```

--------------------------------

### Configure Environment Variables

Source: https://archon.diy/reference/architecture

Define required environment variables in the .env.example file for the new platform.

```bash

# Your Platform
YOUR_PLATFORM_TOKEN=<token>
YOUR_PLATFORM_STREAMING_MODE=stream  # stream | batch

```

--------------------------------

### Configure Global Environment and Server Symlink

Source: https://archon.diy/reference/configuration

Commands to initialize the global configuration directory and link it to the server repository.

```bash
# Create global config
mkdir -p ~/.archon
cp .env.example ~/.archon/.env
# Edit with your values


# For server, symlink to repo
ln -s ~/.archon/.env .env
```

--------------------------------

### Configure Global Settings

Source: https://archon.diy/reference/configuration

Example of a ~/.archon/config.yaml file for setting global AI assistant preferences, streaming, paths, and concurrency limits.

```yaml
# Default AI assistant
defaultAssistant: claude # or 'codex'


# Assistant defaults
assistants:
  claude:
    model: sonnet
    settingSources:   # Which CLAUDE.md files the SDK loads (default: ['project'])
      - project       # Project-level CLAUDE.md (always recommended)
      - user          # Also load ~/.claude/CLAUDE.md (global preferences)
  codex:
    model: gpt-5.3-codex
    modelReasoningEffort: medium
    webSearchMode: disabled
    additionalDirectories:
      - /absolute/path/to/other/repo


# Streaming preferences per platform
streaming:
  telegram: stream # 'stream' or 'batch'
  discord: batch
  slack: batch
  github: batch


# Custom paths (usually not needed)
paths:
  workspaces: ~/.archon/workspaces
  worktrees: ~/.archon/worktrees


# Concurrency limits
concurrency:
  maxConversations: 10


# Env-leak gate bypass (last resort — weakens a security control)
# allow_target_repo_keys: false  # Set true to skip the env-leak-gate
                                 # globally for all codebases on this machine.
                                 # `env_leak_gate_disabled` is logged once per
                                 # process per source. See security.md.
```

--------------------------------

### Bun Log Elision Example

Source: https://archon.diy/contributing/dx-quirks

Example of Bun's log elision when running `bun dev` from the repo root with `--filter`.

```text
@archon/server dev $ bun --watch src/index.ts
│ [129 lines elided]
│ [Hono] Server listening on port 3090
└─ Running...

```

--------------------------------

### Natural Language Approval Example

Source: https://archon.diy/guides/approval-nodes

Example of a user providing a natural language response to an approval prompt, which can be auto-approved and its content captured if 'capture_response' is true.

```text
User: "Looks good, but add error handling for the edge cases"
→ System auto-approves, resumes workflow with your message as $gate.output
  (only if capture_response: true is set)

```

--------------------------------

### Configure Repository Settings

Source: https://archon.diy/reference/configuration

Example of a .archon/config.yaml file for project-specific AI assistant overrides, command loading, worktree settings, and documentation paths.

```yaml
# AI assistant for this project (used as default provider for workflows)
assistant: claude


# Assistant defaults (override global)
assistants:
  claude:
    model: sonnet
    settingSources:  # Override global settingSources for this repo
      - project
  codex:
    model: gpt-5.3-codex
    webSearchMode: live


# Commands configuration
commands:
  folder: .archon/commands
  autoLoad: true


# Worktree settings
worktree:
  baseBranch: main  # Optional: auto-detected from git when not set
  copyFiles:  # Optional: Additional files to copy to worktrees
    - .env.example -> .env  # Rename during copy
    - .vscode               # Copy entire directory


# Documentation directory
docs:
  path: docs  # Optional: default is docs/


# Defaults configuration
defaults:
  loadDefaultCommands: true   # Load app's bundled default commands at runtime
  loadDefaultWorkflows: true  # Load app's bundled default workflows at runtime


# Per-project environment variables for workflow execution (Claude SDK only)
# Injected into the Claude subprocess env. Use the Web UI Settings panel for secrets.
# env:
#   MY_API_KEY: value
#   CUSTOM_ENDPOINT: https://...


# Per-repo override for the env-leak-gate bypass.
# Set to `false` to re-enable the gate for THIS repo even when the global
# config has `allow_target_repo_keys: true`. Set to `true` to grant the
# bypass for THIS repo only. Wins over the global flag in either direction.
# allow_target_repo_keys: false
```

--------------------------------

### Register Adapter in Main Application

Source: https://archon.diy/reference/architecture

Initialize and start the adapter within the server entry point using environment variables.

```typescript

import { YourPlatformAdapter } from './adapters/your-platform';


// Read environment variables
const yourPlatformToken = process.env.YOUR_PLATFORM_TOKEN;
const yourPlatformMode = (process.env.YOUR_PLATFORM_STREAMING_MODE || 'stream') as
  | 'stream'
  | 'batch';


if (yourPlatformToken) {
  const adapter = new YourPlatformAdapter(yourPlatformToken, yourPlatformMode);


  // Set up message handler
  adapter.onMessage(async (conversationId, message) => {
    await handleMessage(adapter, conversationId, message);
  });


  await adapter.start();
  log.info({ platform: 'your-platform' }, 'adapter_started');
}

```

--------------------------------

### Archon Workflow Selection Guide

Source: https://archon.diy/book/essential-workflows

This is a visual guide to help you choose the correct Archon workflow based on your development task. It outlines the different workflows and their primary use cases.

```text
What do you want to do?
│
├── Ask a question or explore the codebase
│   └── archon-assist
│
├── Fix a bug from a GitHub issue
│   └── archon-fix-github-issue
│
├── Build a new feature
│   ├── From an idea or description →  archon-idea-to-pr
│   ├── From an existing plan file  →  archon-plan-to-pr
│   └── Simple implement + PR       →  archon-feature-development
│
├── Review a pull request
│   ├── Adaptive (skips irrelevant agents)  →  archon-smart-pr-review
│   └── All agents, always                  →  archon-comprehensive-pr-review
│
├── Improve codebase architecture
│   └── archon-architect
│
├── Implement a PRD story by story
│   └── archon-ralph-dag
│
└── Resolve merge conflicts
    └── archon-resolve-conflicts
```

--------------------------------

### Archon Configuration Parse Error Example

Source: https://archon.diy/reference/configuration

Example error message indicating invalid YAML syntax in the Archon configuration file. Fix indentation, colons, and special characters in your YAML.

```text
[Config] Failed to parse global config at ~/.archon/config.yaml: <error details>
[Config] Using default configuration. Please fix the YAML syntax in your config file.
```

--------------------------------

### Manual Build for Testing

Source: https://archon.diy/contributing/releasing

Commands to build binaries locally for testing purposes without creating a release.

```bash
# Build all platform binaries
./scripts/build-binaries.sh


# Binaries are in dist/binaries/
ls -la dist/binaries/


# Generate checksums
./scripts/checksums.sh
```

--------------------------------

### Rebuild Docker Image and Start Container

Source: https://archon.diy/reference/troubleshooting

Rebuild the Docker image without using the cache and then start the containers in detached mode. If using specific profiles like 'with-db', append them to the commands.

```bash
docker compose build --no-cache
docker compose up -d
```

--------------------------------

### GET /health/db

Source: https://archon.diy/reference/configuration

Checks the connectivity status of the database.

```APIDOC
## GET /health/db

### Description
Verifies that the application can successfully connect to the database.

### Method
GET

### Endpoint
/health/db

### Response
#### Success Response (200)
- **status** (string) - The status of the application.
- **database** (string) - The connection status, typically 'connected'.

#### Response Example
{
  "status": "ok",
  "database": "connected"
}
```

--------------------------------

### GET /api/config

Source: https://archon.diy/reference/api

Retrieves the read-only configuration subset.

```APIDOC
## GET /api/config

### Description
Get read-only configuration (safe subset).

### Method
GET

### Endpoint
/api/config

### Request Example
curl http://localhost:3090/api/config
```

--------------------------------

### GET /api/conversations

Source: https://archon.diy/reference/api

List all conversations or filter them by codebase.

```APIDOC
## GET /api/conversations

### Description
List all conversations.

### Method
GET

### Endpoint
/api/conversations

### Parameters
#### Query Parameters
- **codebase_id** (string) - Optional - Filter by codebase
- **include_deleted** (boolean) - Optional - Include soft-deleted conversations
```

--------------------------------

### GET /api/health

Source: https://archon.diy/reference/api

Performs an API-level health check.

```APIDOC
## GET /api/health

### Description
Performs an API-level health check.

### Method
GET

### Endpoint
/api/health

### Response
#### Success Response (200)
- **status** (string) - The status of the API
- **adapter** (string) - Adapter information
- **concurrency** (object) - Concurrency metrics
- **runningWorkflows** (number) - Number of active workflows
```

--------------------------------

### Archon Configuration Loading

Source: https://archon.diy/reference/archon-directories

Demonstrates how to load merged configuration for a repository, as well as just the global or repo-specific configuration files.

```typescript
// Load merged config for a repo
const config = await loadConfig(repoPath);


// Load just global config
const globalConfig = await loadGlobalConfig();


// Load just repo config
const repoConfig = await loadRepoConfig(repoPath);

```

--------------------------------

### Troubleshoot Container Startup

Source: https://archon.diy/deployment/local

Commands to diagnose and resolve issues with Archon DIY containers not starting. This includes checking logs, verifying environment configuration, and rebuilding the Docker image without cache.

```bash
# Check logs
docker compose logs app          # default (SQLite or external DB)
docker compose logs app          # --profile with-db


# Verify environment
docker compose config


# Rebuild without cache
docker compose build --no-cache
docker compose up -d
```

--------------------------------

### GET /health/concurrency

Source: https://archon.diy/reference/configuration

Retrieves the current status of the concurrency manager.

```APIDOC
## GET /health/concurrency

### Description
Returns metrics regarding active and queued conversations.

### Method
GET

### Endpoint
/health/concurrency

### Response
#### Success Response (200)
- **status** (string) - The status of the application.
- **active** (integer) - Number of currently active conversations.
- **queued** (integer) - Number of conversations currently in the queue.
- **maxConcurrent** (integer) - The maximum allowed concurrent conversations.

#### Response Example
{
  "status": "ok",
  "active": 0,
  "queued": 0,
  "maxConcurrent": 10
}
```

--------------------------------

### Create New User on Debian/Ubuntu

Source: https://archon.diy/getting-started/overview

Use these commands to create a new user and switch to their session if you are running Archon as root.

```bash
adduser archon          # create user (Debian/Ubuntu)
 usermod -aG sudo archon # give sudo access
 su - archon             # switch to the new user
```

--------------------------------

### Configure server settings

Source: https://archon.diy/deployment/docker

General server configuration variables for the .env file.

```bash
PORT=3000                          # Default: 3000
DOMAIN=archon.example.com          # Required for --profile cloud
LOG_LEVEL=info                     # fatal|error|warn|info|debug|trace
MAX_CONCURRENT_CONVERSATIONS=10
```

--------------------------------

### GET /health

Source: https://archon.diy/reference/configuration

Performs a basic health check to verify if the application is running.

```APIDOC
## GET /health

### Description
Returns the basic operational status of the application.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - The status of the application, typically 'ok'.

#### Response Example
{
  "status": "ok"
}
```

--------------------------------

### Troubleshoot Database Connections

Source: https://archon.diy/deployment/cloud

Commands to test database connectivity, verify environment variables, and apply SQL migrations.

```bash
# Test connection from server
psql $DATABASE_URL -c "SELECT 1"
```

```bash
cat .env | grep DATABASE_URL
```

```bash
psql $DATABASE_URL < migrations/000_combined.sql
```

--------------------------------

### Ask Questions Directly (Telegram)

Source: https://archon.diy/reference/commands

Example of natural language interaction with the bot on Telegram.

```text

You: What's the structure of this repo?


Bot: [Claude analyzes and responds...]

```

--------------------------------

### Create Deployment User and Configure SSH

Source: https://archon.diy/deployment/cloud

Create a new user with sudo privileges and copy the root user's SSH authorized keys to the new user. This enhances security by allowing you to log in as a non-root user. Test the connection in a new terminal before proceeding.

```bash
# Create user with sudo privileges
adduser deploy
usermod -aG sudo deploy

# Copy root's SSH authorized keys to deploy user
mkdir -p /home/deploy/.ssh
cp /root/.ssh/authorized_keys /home/deploy/.ssh/
chown -R deploy:deploy /home/deploy/.ssh
chmod 700 /home/deploy/.ssh
chmod 600 /home/deploy/.ssh/authorized_keys

# Test connection in a new terminal before proceeding:
# ssh -i ~/.ssh/id_ed25519 deploy@your-server-ip
```