Atlas HQ

Atlas HQ is an open-source task routing and agent orchestration system. It sits between your planning work and your AI agents — giving every run structured context, deterministic routing, and verifiable release evidence.

Built for teams running multiple AI agents across multiple projects, sprints, and execution lanes.

What it does

| Capability | Description | |---|---| | Task system | Projects, sprints, tasks, blockers, notes, history, attachments | | Deterministic routing | Rules map task state → correct execution lane | | Agent orchestration | Dispatch jobs, track live runs, record artifacts | | Context distribution | Agents start with the right project/sprint/task brief | | Release truth | Branch → QA → deploy → live verification evidence required before "done" | | Multi-runtime support | OpenClaw, Claude Code, Veri (remote LLM fleet), Webhook | | Contract system | Workflow semantics separated from runtime transport |

Quickstart

npx atlas-hq init
npx atlas-hq start

atlas-hq init walks through first-run setup and writes a ready-to-use .env file.

atlas-hq start starts both the API and UI locally using the configured ports and SQLite path.

If you want defaults immediately, npx atlas-hq is equivalent to npx atlas-hq start.

Open http://localhost:3500 to access the UI by default.

Docker Compose install

The fastest way to get a persistent, self-hosted Atlas HQ running:

git clone https://github.com/nord-initiatives/atlas-hq.git
cd atlas-hq
docker compose up -d

This starts:

• atlas-hq-api — Express/TypeScript API on port 3501
• atlas-hq-ui — Next.js UI on port 3500

Data persists in a named Docker volume (atlas-hq-data).

Custom ports or data directory

Copy the example env file and edit before starting:

cp .env.example .env
# Edit .env: PORT, UI_PORT, ATLAS_HQ_DB_PATH, etc.
docker compose --env-file .env up -d

See docs/SELF_HOSTING.md for the full configuration reference and advanced setup options.

Architecture

┌─────────────────────────────────────────────┐
│               Atlas HQ UI                   │
│          Next.js 14  ·  port 3500           │
│                                             │
│  Tasks | Agents | Chat | Sprints | Routing  │
│  Capabilities | Workspaces | Telemetry      │
└──────────────────┬──────────────────────────┘
                   │ HTTP
                   ▼
┌─────────────────────────────────────────────┐
│               Atlas HQ API                  │
│         Express/TypeScript  ·  port 3501    │
│                                             │
│  task routing · dispatch · lifecycle ·      │
│  contracts · release evidence · watchdog    │
└───────────┬───────────────────┬─────────────┘
            │                   │
            ▼                   ▼
      SQLite database     Agent Runtimes
       atlas-hq.db          │
                             ├─ OpenClaw (local, hooks protocol)
                             ├─ Claude Code (local subprocess)
                             ├─ Veri (remote LLM fleet)
                             └─ Webhook (generic HTTP)

| Layer | Tech | Default port | |---|---|---| | UI | Next.js 14 (App Router) + Tailwind CSS | 3500 | | API | Express + TypeScript | 3501 | | Database | SQLite | — | | Agent runtime | OpenClaw (local, optional) | 18789 | | Agent runtime | Veri tenant API (remote, optional) | — | | Agent runtime | Claude Code (local, optional) | — | | Agent runtime | Webhook (generic HTTP, optional) | — |

Core concepts

Tasks

The unit of planned work. Each task carries a title, description, status, priority, project/sprint placement, blockers, notes, attachments, and release evidence fields (review_commit, qa_verified_commit, deployed_commit, etc.).

Agents

Execution lanes. Each agent is a 1:1 mapping between an identity (name, role, session key) and an execution configuration (schedule, pre-instructions, skills, timeout, dispatch mode). Agents are assigned to projects and process tasks routed to them.

Agents support multiple runtime backends:

• OpenClaw — local agent with shell/file/tool access via the OpenClaw gateway
• Claude Code — local Claude Code agent process with CLAUDE.md management
• Veri — remote agent dispatched via the Veri tenant API with lifecycle proxy
• Webhook — generic HTTP dispatch to any endpoint

Routing rules

Routing is deterministic. Rules match (project, task_type, status) and decide which agent picks up work next and which status transition fires. Multiple rules for the same combination are allowed — the dispatcher tries all matching rules in priority order and picks the first available agent.

Contracts (workflow + transport)

The contract system separates workflow semantics (what outcomes are valid, what evidence is required) from runtime transport (how the agent communicates results back). Three transport modes:

• local — agent runs curl against localhost
• remote-direct — agent makes HTTP calls to an external URL
• proxy-managed — agent emits structured JSON; the runtime handles callbacks

Job instances

Each dispatch creates a job instance with timestamps, session key, artifacts, heartbeat signals, and stale detection.

Release pipeline

Work moves through verifiable states:

todo → ready → dispatched → in_progress → review → qa_pass → ready_to_merge → deployed → done

Atlas HQ requires structured evidence at each gate — branch name, commit SHA, QA URL, deploy target — before allowing progression. PM tasks (pm_analysis, pm_operational) skip QA and post approved_for_merge directly.

UI pages

| Page | Path | Description | |---|---|---| | Dashboard | / | Stats, completed tasks, failed jobs, quick links | | Tasks | /tasks | Kanban board with drag-drop, sprint sections, create task button | | Agents | /agents | Agent list with status, create/edit/delete | | Agent Detail | /agents/[id] | Full-page agent edit with runtime config, skills, logs, docs | | Chat | /chat | Live chat with agents, transcript history, linked task display | | Sprints | /sprints | Sprint list, detail view with metrics and task board | | Capabilities | /capabilities | Skills library + tools registry with enable/disable toggles | | Workspaces | /workspaces | Artifact browser with file editing and syntax highlighting | | Routing | /routing | Routing statuses, transitions, rules, lifecycle rules | | Logs | /logs | Execution logs filtered by agent/level/date | | Telemetry | /telemetry | Task cycle time, QA breakdown, model usage, agent efficiency | | Projects | /projects | Project CRUD with context markdown and file uploads | | Settings | /settings/model-routing | Story points → model mapping configuration |

Configuration reference

All configuration is via environment variables.

API

| Variable | Default | Description | |---|---|---| | PORT | 3501 | API server port | | ATLAS_HQ_DB_PATH | <repo>/atlas-hq.db | SQLite database file path | | ATLAS_HQ_DATA_DIR | <repo> | Base directory for the database (used if ATLAS_HQ_DB_PATH is not set) | | ATLAS_INTERNAL_BASE_URL | http://localhost:3501 | Internal API base URL for local agent callbacks | | ATLAS_HQ_URL | — | External API URL for remote agent callbacks (Veri, webhook) | | OPENCLAW_ENABLED | false | Enable OpenClaw agent dispatch integration | | OPENCLAW_BIN | openclaw | Path to the OpenClaw CLI binary | | OPENCLAW_CONFIG_PATH | ~/.openclaw/openclaw.json | OpenClaw config file path | | OPENCLAW_GATEWAY_URL | https://127.0.0.1:18789 | OpenClaw gateway HTTPS URL | | OPENCLAW_HOOKS_TOKEN | — | Gateway auth token | | WORKSPACE_ROOT | ~/.openclaw/workspace | Agent workspace root directory | | VERI_BASE_URL | — | Veri LLM fleet API base URL | | VERI_API_KEY | — | Bearer token for the Veri API | | VERI_TENANT_URL | — | Veri tenant API base URL | | ANTHROPIC_API_KEY | — | Anthropic API key (for Claude Code runtime) | | TELEGRAM_BOT_TOKEN | — | Telegram bot token for notifications | | TELEGRAM_CHAT_ID | — | Telegram chat ID for notifications |

UI

| Variable | Default | Description | |---|---|---| | PORT | 3500 | UI server port | | NEXT_PUBLIC_API_URL | http://localhost:3501 | Atlas HQ API base URL (set at build time for Docker) |

Agent contract

Agents interact with Atlas HQ via a structured callback protocol injected at dispatch time. The contract adapts based on the agent's transport mode.

Local agents (OpenClaw, Claude Code)

# 1. Start — report session key as soon as the run begins
PUT /api/v1/instances/:id/start
{"session_key": "<sessionKey>"}

# 2. Heartbeat / progress — every 5–10 minutes or on meaningful output
POST /api/v1/instances/:id/check-in
{"stage": "heartbeat", "summary": "Still working", "session_key": "<sessionKey>"}

# 3. Blocker — if blocked before finishing
POST /api/v1/instances/:id/check-in
{"stage": "blocker", "summary": "...", "blocker_reason": "...", "session_key": "<sessionKey>"}

# 4. Task outcome — report before completing the instance
POST /api/v1/tasks/:id/outcome
{"outcome": "completed_for_review", "summary": "...", "changed_by": "<agent-slug>", "instance_id": <id>}

Proxy-managed agents (Veri)

Proxy-managed agents emit a structured JSON block at the end of their response:

{
  "outcome": "completed_for_review",
  "summary": "One sentence describing what was done",
  "branch": "feature/branch-name",
  "commit": "abc1234..."
}

The runtime parses this block and makes lifecycle callbacks on behalf of the agent.

Outcomes

| Outcome | Task moves to | |---|---| | completed_for_review | review | | approved_for_merge | ready_to_merge (PM tasks, skips QA) | | qa_pass | qa_pass | | qa_fail | ready (back to dev) | | deployed_live | deployed | | live_verified | done | | blocked | stalled | | failed | failed |

Running agents with Docker

Atlas HQ ships a parameterized agent container template and a full fleet Compose config. See docker/README.md for the full setup guide.

Quick start — single agent:

docker build \
  -f docker/Dockerfile.agent \
  --build-arg AGENT_ID=agency-backend \
  -t openclaw-agent:agency-backend \
  .

docker run -d \
  -e AGENT_ID="agency-backend" \
  -e OPENCLAW_MODEL="anthropic/claude-sonnet-4-6" \
  -e ANTHROPIC_API_KEY="<key>" \
  -e HOOKS_TOKEN="<token>" \
  -e GATEWAY_AUTH_TOKEN="<gw-token>" \
  -e ATLAS_HQ_API_URL="http://host.docker.internal:3501" \
  -v openclaw-ws-agency-backend:/workspace \
  -p 3711:3700 \
  openclaw-agent:agency-backend

Full fleet (all agents):

cp docker/.env.agents.example .env.agents
# Fill in ANTHROPIC_API_KEY, HOOKS_TOKEN, GATEWAY_AUTH_TOKEN
docker compose -f docker/docker-compose.agents.yml --env-file .env.agents up -d

Contributing

Atlas HQ is open-source and welcomes contributions.

Development setup

git clone https://github.com/nord-initiatives/atlas-hq.git
cd atlas-hq

# Install dependencies
cd api && npm install
cd ../ui && npm install

# Run API (dev mode with live reload)
cd api && npm run dev      # API on port 3501

# Run UI (dev mode)
cd ../ui && npm run dev    # UI on port 3500

Tests:

cd api && npm test

Branch and PR conventions

• Branch names: <author>/task-<id>-<short-slug> (e.g. forge/task-324-readme-docs)
• Open PRs against main
• Include a short summary of what changed and why

What to work on

Check the Issues tab for open work.

Philosophy

If you build on Atlas HQ, optimize for:

• deterministic behavior over magical behavior
• visible state over hidden state
• auditable transitions over silent mutation
• release truth that reflects reality, not aspiration

License

MIT — see LICENSE.