### Local Development Setup with Bun

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/deployment/local.md

Clone the Archon repository, install dependencies using Bun, configure environment variables, and start the development server. SQLite is automatically detected.

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

# 2. Configure environment
cp .env.example .env
nano .env  # Add your AI assistant tokens (Claude, Codex, or Pi)

# 3. Start server + Web UI (SQLite auto-detected, no database setup needed)
bun run dev

# 4. Open Web UI
# http://localhost:5173
```

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

### Full Archon Setup

Source: https://github.com/coleam00/archon/blob/dev/README.md

Clones the Archon repository, installs dependencies, and initiates the setup wizard. Run this from your terminal.

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

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

### Install GitHub CLI on Windows

Source: https://github.com/coleam00/archon/blob/dev/README.md

Installs the GitHub CLI using winget. This is a prerequisite for Archon setup.

```bash
winget install GitHub.cli
```

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

### Run Setup Wizard

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/reference/cli.md

Launch the interactive setup wizard for Archon.

```bash
archon setup
```

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

### Setup User-Wide Archon Defaults

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/reference/configuration.md

This command sequence sets up the user-wide Archon configuration file. It creates the `~/.archon` directory if it doesn't exist and copies an example `.env` file into it.

```bash
mkdir -p ~/.archon
cp .env.example ~/.archon/.env
```

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

### Setup Local Docker Environment

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/deployment/local.md

Configure the .env file with the correct DATABASE_URL, then start the application and PostgreSQL containers using Docker Compose. Monitor logs for startup and verify the health endpoint.

```bash
# 1. Configure .env
# Set: DATABASE_URL=postgresql://postgres:postgres@postgres:5432/remote_coding_agent

# 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
```

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

### Deploy Archon with Pre-built Docker Image

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/deployment/docker.md

Use this command to download the Docker Compose file and environment example, set up your environment, and start Archon using the pre-built image.

```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 Bun on Windows

Source: https://github.com/coleam00/archon/blob/dev/README.md

Installs the Bun JavaScript runtime using PowerShell. This is a prerequisite for Archon setup.

```powershell
irm bun.sh/install.ps1 | iex
```

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

### Configure Environment Variables for Server Setup

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/deployment/docker.md

Copy example configuration files and set essential environment variables in your .env file for server deployment. This includes AI provider tokens, domain, database URL, and optional authentication.

```bash
cp .env.example .env
cp Caddyfile.example Caddyfile
nano .env
```

```ini
# AI Assistant — at least one is required
# Option A: Claude OAuth token (run `claude setup-token` on your local machine to get one)
CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-xxxxx
# Option B: Claude API key (from console.anthropic.com/settings/keys)
# CLAUDE_API_KEY=sk-ant-xxxxx

# Domain — your domain or subdomain pointing to this server
DOMAIN=archon.example.com

# Database — connect to the Docker PostgreSQL container
# Without this, the app uses SQLite (fine for getting started, but PostgreSQL recommended)
DATABASE_URL=postgresql://postgres:postgres@postgres:5432/remote_coding_agent

# Basic Auth (optional) — protects Web UI when exposed to the internet
# Skip if using IP-based firewall rules instead.
# Generate hash: docker run caddy caddy hash-password --plaintext 'YOUR_PASSWORD'
# CADDY_BASIC_AUTH=basicauth @protected { admin $$2a$$14$$... }

# Platform tokens (set the ones you use)
# TELEGRAM_BOT_TOKEN=123456789:ABCdef...
# SLACK_BOT_TOKEN=xoxb-...
# SLACK_APP_TOKEN=xapp-...
# GH_TOKEN=ghp_...
# GITHUB_TOKEN=ghp_...
```

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

### Optional PostgreSQL Setup for Local Development

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/deployment/local.md

Use Docker to start a PostgreSQL instance for local development. Ensure the DATABASE_URL environment variable is set correctly in your .env file.

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

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

### Install GitHub CLI on macOS

Source: https://github.com/coleam00/archon/blob/dev/README.md

Installs the GitHub CLI using Homebrew. This is a prerequisite for Archon setup.

```bash
brew install gh
```

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

### Start Archon Web UI Server

Source: https://github.com/coleam00/archon/blob/dev/CLAUDE.md

Starts the Archon web UI server. The server binary is compiled, and the web UI is downloaded on the first run. Options include specifying a port or downloading without starting.

```bash
bun run cli serve
bun run cli serve --port 4000
bun run cli serve --download-only  # Download without starting
```

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

### Install Archon from Source

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/getting-started/installation.md

Clone the Archon repository and install dependencies using Bun.

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

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

### Install and run agent-browser

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/reference/troubleshooting.md

Install the agent-browser globally and then run it to open a connection. Ensure agent-browser is installed if you encounter 'command not found' errors.

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

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

### Install Bun on macOS/Linux

Source: https://github.com/coleam00/archon/blob/dev/README.md

Installs the Bun JavaScript runtime using a curl command. This is a prerequisite for Archon setup.

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

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

### Local Production Build and Start

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/deployment/local.md

Build the frontend assets for production and then start the Archon server, which will serve both the API and the Web UI.

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

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

### Install GitHub CLI on Linux

Source: https://github.com/coleam00/archon/blob/dev/README.md

Installs the GitHub CLI on Debian/Ubuntu systems using apt. This is a prerequisite for Archon setup.

```bash
sudo apt install gh
```

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

### Install a Skill

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/guides/skills.md

Use this command to install a skill, for example, the official Remotion skill. This places SKILL.md files in the `.claude/skills/` directory.

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

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

### Install Kiro Provider and Dependencies

Source: https://github.com/coleam00/archon/blob/dev/examples/workflows/README.md

Installs the Kiro provider for Pi and other essential command-line tools globally. Ensure Pi is installed before running this.

```bash
pi install npm:pi-provider-kiro
npm install -g @earendil-works/pi-tui @earendil-works/pi-ai
```

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

### Start Development Server or Web UI Individually

Source: https://github.com/coleam00/archon/blob/dev/AGENTS.md

Start only the backend server on port 3090 or the frontend web UI on port 5173.

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

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

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

### Install Skills from Marketplace

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/guides/skills.md

Use 'npx skills add' to install skills from the marketplace. You can install to the current project or globally. Specify a skill name for multi-skill repositories.

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

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

```bash
npx skills add anthropics/skills --skill skill-creator
```

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

### Install and Authenticate glab CLI

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/adapters/community/gitlab.md

Install the glab CLI using Homebrew and then log in to authenticate your account.

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

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

### Install Copilot CLI

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/getting-started/ai-assistants.md

Install the Copilot CLI globally using npm for compiled Archon binaries. This is required if you are not using a source install with `bun run`.

```bash
npm install -g @github/copilot
```

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

### Project Configuration Example

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/getting-started/configuration.md

Create a `.archon/config.yaml` file in your repository to define assistant models and other project settings. This example shows how to configure Claude and Codex assistants.

```yaml
assistants:
  claude:
    model: sonnet  # or 'opus', 'haiku', 'inherit'
    settingSources:
      - project
  codex:
    model: gpt-5.3-codex
    modelReasoningEffort: medium

# docs:
#   path: packages/docs-web/src/content/docs  # Optional: default is docs/
```

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

### Install agent-browser

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/deployment/e2e-testing.md

Global installation of the agent-browser package and its required browser engine.

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

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

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

### Start Services with Local PostgreSQL

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/deployment/cloud.md

Use this command to start the application, PostgreSQL, and Caddy when using a local PostgreSQL database. It builds the images and starts services in detached mode.

```bash
# Start app, postgres, and Caddy
docker compose --profile with-db --profile cloud up -d --build

# View logs
docker compose --profile with-db --profile cloud logs -f app
docker compose --profile with-db --profile cloud logs -f postgres
```

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

### Install Docker

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/deployment/cloud.md

This script downloads and installs Docker. After installation, add the 'deploy' 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 Archon with Docker Compose

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/deployment/docker.md

After configuring the .env file, use this command to start Archon and its associated services, including PostgreSQL.

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

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

### Copy Caddyfile Example

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/deployment/cloud.md

Copy the example Caddyfile to your project. No manual editing is required as it reads domain and port from the .env file.

```bash
# Copy the example — no manual editing needed
cp Caddyfile.example Caddyfile
```

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

### Verify the Release

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/contributing/releasing.md

Test the installation script and verify the installed version of the CLI.

```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
```

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

### Full workflow example with hooks

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/guides/hooks.md

A comprehensive workflow example demonstrating the use of `PreToolUse` and `PostToolUse` hooks to enforce security and context for code review tasks.

```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 on Windows

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/docs.mdx

Use this command to install Archon on Windows systems.

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

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

### Install Archon via Homebrew

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/docs.mdx

Install Archon using the Homebrew package manager.

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

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

### Verify Archon Setup (CLI)

Source: https://github.com/coleam00/archon/blob/dev/AGENTS.md

Runs a diagnostic check to verify the Archon setup, including the Claude binary, GitHub authentication, database, and adapters.

```bash
bun run cli doctor
```

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

### Install via GitHub CLI

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/contributing/releasing.md

Use the GitHub CLI to download and install binaries when the repository is private.

```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 Skill (CLI)

Source: https://github.com/coleam00/archon/blob/dev/AGENTS.md

Installs the bundled Archon skill into a specified project directory.

```bash
bun run cli skill install
```

```bash
bun run cli skill install /path/to/project
```

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

### Install Project Dependencies

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/getting-started/overview.md

Run this command after cloning the repository to install all necessary project dependencies across the monorepo. This typically takes about 30 seconds.

```bash
bun install
```

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

### Run the interactive setup wizard

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/reference/cli.md

The `setup` command launches an interactive wizard for configuring credentials and settings. It can write to different scopes (`home` or `project`), force overwrites, or spawn in a new terminal.

```bash
archon setup                      # writes ~/.archon/.env (home scope, default)
```

```bash
archon setup --scope project      # writes <cwd>/.archon/.env instead
```

```bash
archon setup --force              # overwrite instead of merging (backup still written)
```

```bash
archon setup --spawn              # open in a new terminal window
```

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

### Start Archon from Project Directory

Source: https://github.com/coleam00/archon/blob/dev/README.md

Navigates to a project directory and initiates the Archon CLI. Archon will automatically register the project.

```bash
cd /path/to/your/project
claude
```

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

### Build and Start Web UI in Production

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/adapters/web.md

Builds the frontend into static files and then starts the server to serve both the API and the Web UI on port 3090. No separate frontend URL is needed in production.

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

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

### Install Claude Code on Windows

Source: https://github.com/coleam00/archon/blob/dev/README.md

Installs the Claude Code CLI using PowerShell. This is a prerequisite for Archon setup.

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

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

### Copy Environment Example File

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/getting-started/overview.md

Create a .env file for configuration by copying the provided .env.example file. This is required for Web UI/server mode and optional for CLI-only usage.

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

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

### Install and Configure plannotator Extension

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/getting-started/ai-assistants.md

Install the plannotator Pi extension and configure its flags and environment variables in `.archon/config.yaml`. The `PLANNOTATOR_REMOTE` environment variable exposes the review URL.

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

```yaml
# .archon/config.yaml
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
```

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

### Install Claude Code on macOS/Linux/WSL

Source: https://github.com/coleam00/archon/blob/dev/README.md

Installs the Claude Code CLI using a curl command. This is a prerequisite for Archon setup.

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

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

### Serve Archon Web UI (CLI)

Source: https://github.com/coleam00/archon/blob/dev/AGENTS.md

Starts the Archon web UI server. The binary downloads the web UI on its first run. Options include specifying a port or only downloading the UI without starting the server.

```bash
bun run cli serve
```

```bash
bun run cli serve --port 4000
```

```bash
bun run cli serve --download-only
```

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

### Clone Archon Repository (/opt Server Install)

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/getting-started/overview.md

This command clones the Archon repository into the /opt directory for server installations on Linux/macOS, ensuring a tidy setup.

```bash
sudo mkdir -p /opt/archon
sudo chown $USER:$USER /opt/archon
git clone https://github.com/coleam00/Archon /opt/archon
cd /opt/archon
```

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

### Create and Edit Environment File

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/deployment/cloud.md

Copy the example environment file and edit it using nano to configure application settings.

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

# Edit with nano
nano .env
```

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

### Check Docker container logs

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/reference/troubleshooting.md

View the logs for the 'app' service in your Docker Compose setup to identify specific errors when a container fails to start.

```bash
docker compose logs app
```

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

### Start Development Servers on Windows

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/deployment/e2e-testing-wsl.md

Commands to launch backend and frontend servers, 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 &
```

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

### Workflow Description Example

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/guides/authoring-workflows.md

A good workflow description clearly states its purpose, usage conditions, expected outputs, and high-level steps. Use this format to guide users and improve routing.

```yaml
description: |
  Investigate and fix a GitHub issue end-to-end.

  **Use when**: User provides a GitHub issue number or URL
  **NOT for**: Feature requests, refactoring, documentation

  **Produces**:
  - Investigation artifact
  - Code changes
  - Pull request linked to issue

  **Steps**:
  1. Investigate root cause
  2. Implement fix with tests
  3. Create PR
```

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

### Environment Variables Example (.env.example)

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/reference/architecture.md

Example configuration file showing necessary environment variables for a custom AI assistant provider. This includes API keys and model names required for authentication and operation.

```ini
# Your Assistant
YOUR_ASSISTANT_API_KEY=<key>
YOUR_ASSISTANT_MODEL=<model-name>
```

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

### Python Script with Dependencies

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/guides/script-nodes.md

Example of a Python script using `uv` runtime with explicit dependencies. The `deps` field allows specifying packages that will be installed in an ephemeral environment for the script's execution.

```yaml
- id: scrape
  script: |
    import httpx
    r = httpx.get("https://api.github.com/repos/anthropics/anthropic-cookbook")
    print(r.text)
  runtime: uv
  deps: ["httpx>=0.27"]
```

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

### Environment Variables for Platform Adapter

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/reference/architecture.md

Example `.env.example` file showing required environment variables for configuring a platform adapter, such as API tokens and streaming mode.

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

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

### Install WSL2

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/deployment/windows.md

Installs the Windows Subsystem for Linux, which provides a Linux environment on Windows. Restart your computer after installation.

```powershell
wsl --install
```

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

### Install MCP Adapter for Pi

Source: https://github.com/coleam00/archon/blob/dev/examples/workflows/README.md

Installs the MCP adapter for Pi. This command requires Pi to be installed first.

```bash
pi install npm:pi-mcp-adapter
```

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

### Registering Platform Adapter in Main App

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/reference/architecture.md

Demonstrates how to instantiate and start a platform adapter within the main server application. Includes reading environment variables and setting up message handlers.

```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');
}
```

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

### Install Pi Coding Agent

Source: https://github.com/coleam00/archon/blob/dev/examples/workflows/README.md

Installs the Pi coding agent globally using npm. This is a prerequisite for further installations.

```bash
npm install -g @earendil-works/pi-coding-agent
```

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

### Download and Configure Docker Deployment Files

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/deployment/local.md

Fetches the necessary Docker Compose and environment files, then prompts for configuration.

```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

# Configure (edit .env with your tokens and DATABASE_URL)
ano .env
```

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

### Install Archon Skills

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/reference/cli.md

Installs bundled Archon skills into the project's `.claude/skills/` and `.agents/skills/` directories. This command overwrites existing files to ensure the latest version is installed. It can install into the current directory or a specified project path.

```bash
# Install into the current directory
archon skill install
```

```bash
# Install into a specific project
archon skill install /path/to/project
```

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

### Install Claude Code (macOS/Linux/WSL)

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/getting-started/installation.md

Install Claude Code using Anthropic's recommended installer script for macOS, Linux, or WSL.

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

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

### Quick Start Local Docker Deployment

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/deployment/docker.md

Clone the repository, set up the environment variables, and start Archon using Docker Compose for local development. Access the Web UI at http://localhost:3000.

```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
```

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

### YourPlatformAdapter Implementation Example

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/reference/architecture.md

A concrete implementation of the IPlatformAdapter interface for a custom platform. Includes constructor, message sending, streaming mode, platform type, and start/stop methods.

```typescript
import type { IPlatformAdapter } from '@archon/core';

export class YourPlatformAdapter implements IPlatformAdapter {
  private streamingMode: 'stream' | 'batch';

  constructor(config: YourPlatformConfig, mode: 'stream' | 'batch' = 'stream') {
    this.streamingMode = mode;
    // Initialize your platform SDK/client
  }

  async sendMessage(conversationId: string, message: string): Promise<void> {
    // Platform-specific message sending logic
    // Handle message length limits, formatting, etc.
  }

  getStreamingMode(): 'stream' | 'batch' {
    return this.streamingMode;
  }

  getPlatformType(): string {
    return 'your-platform'; // Used as platform_type in database
  }

  async start(): Promise<void> {
    // Start polling, webhook server, WebSocket connection, etc.
    // Example: this.client.startPolling();
  }

  stop(): void {
    // Cleanup: stop polling, close connections
  }
}
```

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

### Set up PostgreSQL Database

Source: https://github.com/coleam00/archon/blob/dev/AGENTS.md

Optional: Use PostgreSQL instead of SQLite by starting the PostgreSQL service via Docker Compose and setting the DATABASE_URL in your .env file.

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

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

### Install Codex CLI using npm

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/getting-started/ai-assistants.md

Install the Codex CLI globally using npm. This is the primary installation method for any platform. OpenAI recommends WSL2 for Windows.

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

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

### Start Full Server Deployment

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/deployment/docker.md

Launch Archon with PostgreSQL and Caddy reverse proxy using Docker Compose profiles. This command starts the app, database, and Caddy containers.

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

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

### Install Docker on Ubuntu/Debian

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/deployment/docker.md

Install Docker and Docker Compose on Ubuntu/Debian systems using the official installation script. Add your user to the 'docker' group to run commands without sudo.

```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
```

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

### Start Services with Remote PostgreSQL

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/deployment/cloud.md

Use this command to start the application with Caddy reverse proxy when using a remote managed database. It builds the images and starts services in detached mode.

```bash
# Start app with Caddy reverse proxy
docker compose --profile cloud up -d --build

# View logs
docker compose --profile cloud logs -f app
```

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

### Install Archon CLI

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/book/first-five-minutes.md

Clone the Archon repository, install dependencies with Bun, and then link the CLI globally for easy access. If the command is not found, try sourcing your shell configuration or using `bun run cli`.

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

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

archon version
```

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

### Serve Archon Web UI

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/reference/cli.md

Starts the Archon web UI server. On the first run, it downloads and caches the web UI. The `--port` flag can override the default port, and `--download-only` allows downloading without starting the server.

```bash
# Start web UI server (downloads on first run)
archon serve
```

```bash
# Override the default port
archon serve --port 4000
```

```bash
# Download the web UI without starting the server
archon serve --download-only
```

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

### Create a Remotion Project

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/guides/remotion-workflow.md

Use this command to quickly scaffold a new Remotion video project and install its dependencies.

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

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

### Start Web UI in Development

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/adapters/web.md

Starts both the backend API server and the frontend development server with hot reloading. The Web UI will be accessible at http://localhost:5173 and the API server at http://localhost:3090.

```bash
bun run dev
# Web UI: http://localhost:5173
# API server: http://localhost:3090
```

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

### Install Archon on macOS/Linux

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/docs.mdx

Use this command to install Archon on macOS or Linux systems.

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

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

### Assistant Configuration Example

Source: https://github.com/coleam00/archon/blob/dev/AGENTS.md

Configure default models and options for AI assistants in the .archon/config.yaml file. This includes setting models, controlling setting sources, and specifying binary paths.

```yaml
assistants:
  claude:
    model: sonnet # or 'opus', 'haiku', 'claude-*', 'inherit'
    settingSources: # Controls which CLAUDE.md, skills, commands, and agents the SDK loads
      - project # Project-level <cwd>/.claude/ (included in default)
      - user # User-level ~/.claude/ (included in default; omit both to restrict to project-only)
    claudeBinaryPath:
      /absolute/path/to/claude # Optional: Claude Code executable.
      # Native binary (curl installer at
      # ~/.local/bin/claude), npm cli.js, or
      # the npm platform-package directory
      # (e.g. @anthropic-ai/claude-code-win32-x64)
      # which is auto-expanded to claude/claude.exe.
      # Required in compiled binaries if
      # CLAUDE_BIN_PATH env var is not set.
  codex:
    model: gpt-5.3-codex
    modelReasoningEffort: medium # 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
    webSearchMode: live # 'disabled' | 'cached' | 'live'
    additionalDirectories:
      - /absolute/path/to/other/repo
    codexBinaryPath: /usr/local/bin/codex # Optional: custom Codex CLI binary path


# docs:
#   path: docs  # Optional: default is docs/
```

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

### YourAssistantProvider Implementation Example

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/reference/architecture.md

An example implementation of the IAgentProvider interface for a custom AI assistant. It demonstrates how to handle session management, stream responses from an SDK, and yield different MessageChunk types, including assistant messages, tool calls, and session results.

```typescript
import type { IAgentProvider, MessageChunk, ProviderCapabilities, SendQueryOptions } from '../types';

export class YourAssistantProvider implements IAgentProvider {
  async *sendQuery(
    prompt: string,
    cwd: string,
    resumeSessionId?: string,
    options?: SendQueryOptions,
  ): AsyncGenerator<MessageChunk> {
    // Initialize or resume session
    const session = resumeSessionId
      ? await this.resumeSession(resumeSessionId)
      : await this.startSession(cwd);

    // Send query to AI and stream responses
    for await (const event of this.sdk.streamQuery(session, prompt)) {
      if (event.type === 'text_response') {
        yield { type: 'assistant', content: event.text };
      } else if (event.type === 'tool_call') {
        yield {
          type: 'tool',
          toolName: event.tool,
          toolInput: event.parameters,
          toolCallId: event.id,
        };
      } else if (event.type === 'thinking') {
        yield { type: 'thinking', content: event.reasoning };
      }
    }

    // Yield session ID for persistence
    yield { type: 'result', sessionId: session.id };
  }

  getType(): string {
    return 'your-assistant';
  }

  getCapabilities(): ProviderCapabilities {
    // Declare only what you've actually wired. Under-declaration is honest;
    // the dag-executor warns users if a workflow node uses a feature you
    // declared unsupported.
    return YOUR_ASSISTANT_CAPABILITIES;
  }
}
```

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

### Archon Retry Notification Example

Source: https://github.com/coleam00/archon/blob/dev/packages/docs-web/src/content/docs/guides/authoring-workflows.md

Example of a platform notification displayed before each retry attempt.

```text
Node `node-id` failed with transient error (attempt 1/3). Retrying in 3s...
```