Getting Started with Aragora

Last Updated: 2026-01-27

Aragora is the control plane for multi-agent vetted decisionmaking across organizational knowledge and channels. It orchestrates diverse AI models to debate your data and deliver defensible decisions wherever your team works. This is the canonical onboarding guide.

Choose your path:

Quick Start - Get running in 5 minutes
CLI User Guide - Run debates from the terminal
API Integrator Guide - Build on Aragora's API
Live Dashboard Dev - Build the Next.js UI
TypeScript SDK - Use the JS client library
Gauntlet Guide - Stress-test documents and policies
Troubleshooting - Fix common issues

Quick Start

1. Install

git clone https://github.com/an0mium/aragora.git
cd aragora
pip install -e .

2. Configure (Choose One)

Option A: Interactive Setup Wizard (Recommended)

The easiest way to configure Aragora:

aragora setup

The wizard guides you through:

API key configuration with validation
Server port settings
Database selection (SQLite/PostgreSQL)
Optional integrations (Slack, GitHub, Telegram)

See the CLI Setup Guide for detailed options.

Option B: Manual Configuration

Create a .env file with at least one AI provider key:

cp .env.starter .env

Edit .env (or use .env.example for the full template):

# Required: At least one of these
ANTHROPIC_API_KEY=sk-ant-xxx     # Claude (recommended)
OPENAI_API_KEY=sk-xxx            # GPT-4
GEMINI_API_KEY=AIzaSy...         # Gemini
XAI_API_KEY=xai-xxx              # Grok
MISTRAL_API_KEY=xxx              # Mistral (optional)
OPENROUTER_API_KEY=sk-or-xxx     # OpenRouter (optional)

Optional but recommended: keep runtime data out of the repo root.

ARAGORA_DATA_DIR=.nomic

3. Verify Setup

aragora doctor

Expected output:

Aragora Health Check
====================
API Keys:
  Anthropic: OK
  OpenAI: OK
  Gemini: Not configured
  Grok: Not configured

Environment:
  Python: 3.10.13
  aragora: 2.6.3

Status: Ready

Optional: run the golden-path harness (offline, demo agents).

python scripts/golden_paths.py --mode fast
python scripts/golden_paths.py --mode fast --enable-trending  # optional network context

Sample artifacts live in examples/golden_paths/demo.

4. Run Your First Stress-Test

aragora ask "Should we use microservices or monolith?" \
  --agents anthropic-api,openai-api

Expected output:

DEBATE: Should we use microservices or monolith?
Agents: anthropic-api, openai-api
Round 1/3...
  [anthropic-api] Proposing...
  [openai-api] Critiquing...
...
CONSENSUS REACHED (75% agreement)
Final Answer: [synthesized recommendation]

CLI User Guide

Basic Usage

aragora ask "<your question>" --agents <agent1>,<agent2>

Note: the CLI default is codex,claude (local CLI agents). If you only have API keys, use --agents anthropic-api,openai-api or another API-backed set.

Available Agents

Agent	Provider	API Key Required
`anthropic-api`	Claude (Anthropic)	`ANTHROPIC_API_KEY`
`openai-api`	OpenAI	`OPENAI_API_KEY`
`gemini`	Google Gemini	`GEMINI_API_KEY`
`grok`	xAI Grok	`XAI_API_KEY`
`mistral-api`	Mistral (direct)	`MISTRAL_API_KEY`
`codestral`	Mistral (code)	`MISTRAL_API_KEY`
`deepseek`	OpenRouter	`OPENROUTER_API_KEY`
`qwen` / `qwen-max`	OpenRouter	`OPENROUTER_API_KEY`
`kimi`	Moonshot (Kimi)	`KIMI_API_KEY`
`ollama`	Local models	None (local)

Note: OpenRouter agents require OPENROUTER_API_KEY. Full catalog is in AGENTS.md.

Common Options

# More rounds (deeper debate)
aragora ask "..." --rounds 5

# Consensus mode
aragora ask "..." --consensus majority    # 60% agreement (default)
aragora ask "..." --consensus unanimous   # All agents agree
aragora ask "..." --consensus judge       # One agent decides

# Add context
aragora ask "..." --context "Consider latency and cost"

# Verbose output
aragora ask "..." --verbose

Example Debates

# Architecture decision
aragora ask "Design a caching strategy for 10M users" \
  --agents anthropic-api,openai-api,gemini --rounds 4

# Code review
aragora ask "Review this code for security issues: $(cat myfile.py)" \
  --agents anthropic-api,openai-api --consensus unanimous

# Framework comparison
aragora ask "React vs Vue vs Svelte for our new project" \
  --agents anthropic-api,openai-api,gemini,grok

Code Review

Review pull requests with unanimous AI consensus:

# Review local changes
git diff main | aragora review

# Review GitHub PR
aragora review https://github.com/owner/repo/pull/123

# Demo mode (no API keys)
aragora review --demo

Vertical Specialists

Industry-specific debate templates with pre-configured agents, tools, and compliance frameworks:

# List available verticals
aragora verticals list

# Filter by keyword
aragora verticals list --keyword healthcare

# Get vertical configuration
aragora verticals get healthcare

# List tools for a vertical
aragora verticals tools fintech

# Show compliance frameworks
aragora verticals compliance healthcare

# Suggest vertical for a task
aragora verticals suggest --task "Analyze HIPAA compliance for patient portal"

Available verticals include: healthcare, fintech, legal, devops, security, and more.

Memory Operations

Inspect and manage the multi-tier memory system:

# Query memories by prefix
aragora memory query "debate:arch:"

# Store a memory entry
aragora memory store "custom:key" "value data" --tier medium

# View memory statistics
aragora memory stats

# Promote memory to a longer-lived tier
aragora memory promote "key" --to slow

Memory tiers: fast (1 min TTL), medium (1 hour), slow (1 day), glacial (1 week).

Knowledge Mound

Query and manage the unified knowledge store:

# Query knowledge by prefix
aragora km query "consensus:"

# Store knowledge entry
aragora km store "insights:arch:caching" '{"pattern": "write-through"}'

# View knowledge statistics
aragora km stats

# List knowledge by category
aragora km query "evidence:" --limit 10

Start Dashboard

aragora serve
# Open http://localhost:8080

API Integrator Guide

Start the Server

aragora serve --api-port 8080 --ws-port 8765

Core Endpoints

Endpoint	Method	Description
`/api/debates`	POST	Start a new debate
`/api/debates/\{id\}`	GET	Get debate status/results
`/api/debates`	GET	List recent debates
`/api/agents`	GET	List available agents
`/api/health`	GET	Health check

Start a Debate

curl -X POST http://localhost:8080/api/debates \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Should we use microservices or monolith?",
    "agents": ["anthropic-api", "openai-api"],
    "rounds": 3,
    "consensus": "majority"
  }'

Response:

{
  "debate_id": "debate-20260111-abc123",
  "status": "running",
  "task": "Should we use microservices or monolith?"
}

Get Debate Results

curl http://localhost:8080/api/debates/debate-20260111-abc123

Response:

{
  "debate_id": "debate-20260111-abc123",
  "status": "completed",
  "task": "Should we use microservices or monolith?",
  "consensus": {
    "reached": true,
    "agreement": 0.75,
    "final_answer": "..."
  },
  "rounds": [...],
  "participants": ["anthropic-api", "openai-api"]
}

WebSocket Streaming

For real-time debate updates:

const ws = new WebSocket('ws://localhost:8765/ws');
const loopId = 'debate-20260111-abc123';

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (['connection_info', 'loop_list', 'sync'].includes(data.type)) return;

  const eventLoopId = data.loop_id || data.data?.debate_id || data.data?.loop_id;
  if (eventLoopId && eventLoopId !== loopId) return;

  console.log(data.type, data.data);
  // Types: debate_start, agent_message, critique, vote, consensus, debate_end
};

Authentication

For protected endpoints, use Bearer token:

curl http://localhost:8080/api/protected \
  -H "Authorization: Bearer YOUR_TOKEN"

Generate a token:

curl -X POST http://localhost:8080/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username": "user", "password": "pass"}'

Full API Reference

See API_REFERENCE.md for the full endpoint catalog.

Gauntlet Guide

The Gauntlet stress-tests documents, policies, and code using 12+ AI agents simulating hackers, regulators, and critics.

Quick Demo

Run with simulated agents (no API keys needed):

python examples/gauntlet_demo.py

Stress-Test Your Documents

# CLI usage
aragora gauntlet my_policy.md --persona gdpr

# With specific profile
aragora gauntlet my_spec.md --profile thorough

# Code security review
aragora gauntlet src/auth.py --profile code

Gauntlet Profiles

Profile	Duration	Best For
`quick`	2 min	Fast validation
`default`	5 min	Balanced analysis
`thorough`	15 min	Comprehensive review
`code`	10 min	Security-focused code
`policy`	10 min	Compliance-focused

Regulatory Personas

Persona	Focus
`gdpr`	GDPR compliance (consent, data rights, transfers)
`hipaa`	HIPAA compliance (PHI, safeguards, breach)
`ai_act`	EU AI Act (risk levels, transparency, bias)
`security`	Security vulnerabilities (injection, auth, crypto)
`soc2`	SOC 2 controls (security, availability)
`pci_dss`	PCI DSS (cardholder data, encryption)

Gauntlet via API

# Start a gauntlet run
curl -X POST http://localhost:8080/api/gauntlet/run \
  -H "Content-Type: application/json" \
  -d '{
    "input_content": "Your policy content here...",
    "input_type": "policy",
    "persona": "gdpr",
    "profile": "default"
  }'

# Get status
curl http://localhost:8080/api/gauntlet/\{id\}

# Get Decision Receipt
curl http://localhost:8080/api/gauntlet/\{id\}/receipt?format=html

# Get Risk Heatmap
curl http://localhost:8080/api/gauntlet/\{id\}/heatmap?format=svg

Understanding Results

The Decision Receipt contains:

Verdict: APPROVED, APPROVED_WITH_CONDITIONS, NEEDS_REVIEW, or REJECTED
Risk Score: 0-100% risk assessment
Findings: Issues categorized by severity (Critical, High, Medium, Low)
Mitigations: Recommended fixes for each finding
Audit Trail: Full evidence chain for compliance

Troubleshooting

"No API key found"

Error: No API key configured for anthropic-api

Solution: Set at least one key in .env or environment:

export ANTHROPIC_API_KEY=your-key
# Or add to .env file

Verify: Run aragora doctor to check configuration.

"Agent timed out"

Error: Agent anthropic-api timed out after 60s

Cause: API provider is slow or overloaded.

Solutions:

Increase timeout:

export ARAGORA_DEBATE_TIMEOUT=1200  # seconds

Use fewer agents
Try a different provider

"Rate limit exceeded"

Error: Rate limit exceeded for openai-api

Solutions:

Wait 60 seconds and retry
Use fewer agents

Use fallback providers:

# OpenRouter provides fallback access
export OPENROUTER_API_KEY=sk-or-xxx

"Connection refused on port 8080"

Error: Connection refused on localhost:8080

Cause: Server not running or port in use.

Solutions:

Start the server:
```
aragora serve
```
Use a different port:
```
aragora serve --api-port 8081
```
Check what's using the port:
```
lsof -i :8080
```

"Invalid API key"

Error: Invalid API key for anthropic-api

Cause: API key is malformed or expired.

Solutions:

Verify the key format:
- Anthropic: sk-ant-api03-...
- OpenAI: sk-...
- Gemini: AIzaSy...
Regenerate the key in your provider dashboard
Check for extra whitespace in .env

"Module not found"

Error: ModuleNotFoundError: No module named 'aragora'

Solution: Install in development mode:

pip install -e .

Still stuck?

Run diagnostics: aragora doctor
Check logs: tail -f ~/.aragora/logs/aragora.log
File an issue: https://github.com/an0mium/aragora/issues

Next Steps

Deep Dive: Architecture Guide
All Options: Environment Variables
Full API: API Reference
Gauntlet Details: Gauntlet Guide
Self-Improvement: Nomic Loop
Custom Agents: Custom Agents Guide

Quick Reference

CLI Commands

Command	Description
`aragora ask "..."`	Run a debate
`aragora review`	Review code/PR
`aragora gauntlet`	Stress-test documents
`aragora serve`	Start dashboard
`aragora doctor`	Check health
`aragora status`	Show environment
`aragora config`	Manage settings
`aragora verticals`	Industry-specific debate templates
`aragora memory`	Memory tier operations
`aragora km`	Knowledge Mound operations

Environment Variables

Quick Reference (see ENVIRONMENT.md for complete reference):

Variable	Description	Required
`ANTHROPIC_API_KEY`	Claude API key	At least one
`OPENAI_API_KEY`	GPT-4 API key	At least one
`GEMINI_API_KEY`	Gemini API key	Optional
`XAI_API_KEY`	Grok API key	Optional
`MISTRAL_API_KEY`	Mistral API key	Optional
`OPENROUTER_API_KEY`	Fallback provider	Recommended

Configuration Templates:

.env.starter - Minimal config to get started
.env.example - Full configuration reference

Health Endpoints

Endpoint	Description
`/healthz`	Kubernetes liveness probe
`/readyz`	Kubernetes readiness probe
`/api/health`	Comprehensive health check
`/api/health/detailed`	Detailed component status

Quick Start​

1. Install​

2. Configure (Choose One)​

Option A: Interactive Setup Wizard (Recommended)​

Option B: Manual Configuration​

3. Verify Setup​

4. Run Your First Stress-Test​

CLI User Guide​

Basic Usage​

Available Agents​

Common Options​

Example Debates​

Code Review​

Vertical Specialists​

Memory Operations​

Knowledge Mound​

Start Dashboard​

API Integrator Guide​

Start the Server​

Core Endpoints​

Start a Debate​

Get Debate Results​

WebSocket Streaming​

Authentication​

Full API Reference​

Gauntlet Guide​

Quick Demo​

Stress-Test Your Documents​

Gauntlet Profiles​

Regulatory Personas​

Gauntlet via API​

Understanding Results​

Troubleshooting​

"No API key found"​

"Agent timed out"​

"Rate limit exceeded"​

"Connection refused on port 8080"​

"Invalid API key"​

"Module not found"​

Still stuck?​

Next Steps​

Quick Reference​

CLI Commands​

Environment Variables​

Health Endpoints​

Quick Start

1. Install

2. Configure (Choose One)

Option A: Interactive Setup Wizard (Recommended)

Option B: Manual Configuration

3. Verify Setup

4. Run Your First Stress-Test

CLI User Guide

Basic Usage

Available Agents

Common Options

Example Debates

Code Review

Vertical Specialists

Memory Operations

Knowledge Mound

Start Dashboard

API Integrator Guide

Start the Server

Core Endpoints

Start a Debate

Get Debate Results

WebSocket Streaming

Authentication

Full API Reference

Gauntlet Guide

Quick Demo

Stress-Test Your Documents

Gauntlet Profiles

Regulatory Personas

Gauntlet via API

Understanding Results

Troubleshooting

"No API key found"

"Agent timed out"

"Rate limit exceeded"

"Connection refused on port 8080"

"Invalid API key"

"Module not found"

Still stuck?

Next Steps

Quick Reference

CLI Commands

Environment Variables

Health Endpoints