Skip to content

Configuration

Jump to bottom
Jason L. West edited this page Feb 6, 2026 · 2 revisions

Configuration

All configuration is done through environment variables. Copy the example files and edit as needed:

cp .env.example .env                    # Core agent
cp .env.swarm.example .env.swarm        # Swarm system

Core Agent

Variable Default Description
NEBULUS_BASE_URL http://localhost:5000/v1 LLM server URL
NEBULUS_API_KEY admin API key for LLM server
NEBULUS_MODEL Meta-Llama-3.1-8B-Instruct-exl2-8_0 Model name
NEBULUS_TIMEOUT 300 Request timeout in seconds
NEBULUS_STREAMING true Enable streaming responses
COMPOSE_PROJECT_NAME nebulus-atom Docker Compose project name

Slack Integration

Variable Default Description
SLACK_BOT_TOKEN - Slack Bot OAuth Token (xoxb-...)
SLACK_APP_TOKEN - Slack App-Level Token for Socket Mode (xapp-...)
SLACK_CHANNEL_ID - Channel ID to monitor

Setting Up Slack

  1. Create a Slack App at api.slack.com/apps
  2. Enable Socket Mode and generate an App-Level Token
  3. Add Bot Token scopes: chat:write, channels:read, channels:history
  4. Install app to workspace
  5. Copy the Bot Token and App Token to your .env
  6. Invite the bot to your channel

GitHub Integration

Variable Default Description
GITHUB_TOKEN - Personal Access Token
GITHUB_WATCHED_REPOS - Comma-separated repos (e.g., owner/repo1,owner/repo2)
GITHUB_DEFAULT_REPO - Default repository for Slack commands

Required Token Scopes

  • repo - Full repository access
  • read:org - Read org membership (for private repos)

Minion Configuration

Variable Default Description
MAX_CONCURRENT_MINIONS 3 Maximum concurrent minion containers
MINION_TIMEOUT_MINUTES 30 Minion timeout before being killed

LLM Backend (Minions)

Variable Default Description
NEBULUS_BASE_URL http://localhost:5000/v1 LLM server URL for minions
NEBULUS_MODEL qwen3-coder-30b Model for minion work
NEBULUS_TIMEOUT 600 LLM request timeout
NEBULUS_STREAMING false Enable streaming

Overlord LLM (Command Parsing)

Variable Default Description
OVERLORD_LLM_ENABLED true Enable LLM-powered command parsing
OVERLORD_LLM_BASE_URL http://localhost:5000/v1 LLM server for Overlord
OVERLORD_LLM_MODEL llama-3.1-8b Small model for fast parsing
OVERLORD_LLM_TIMEOUT 5.0 Parsing timeout (seconds)
OVERLORD_LLM_CONFIDENCE 0.7 Minimum confidence threshold
OVERLORD_LLM_CONTEXT_MAX 10 Max context entries per channel
OVERLORD_LLM_CONTEXT_TTL 30 Context TTL in minutes

Model Routing

Variable Default Description
ROUTING_ENABLED false Enable multi-LLM routing
ROUTING_COMPLEXITY_THRESHOLD 5 Score threshold (0-10) for heavy tier
ROUTING_DEFAULT_TIER heavy Fallback tier when routing fails
ROUTING_MODELS - JSON string with model profiles (see below)

Model Profiles JSON

ROUTING_MODELS='{
  "light": {
    "name": "llama-3.1-8b",
    "base_url": "http://localhost:5000/v1",
    "timeout": 300
  },
  "heavy": {
    "name": "qwen3-coder-30b",
    "base_url": "http://gpu-server:8080/v1",
    "timeout": 600
  }
}'

See Model Router for details.

Cron Configuration

Variable Default Description
CRON_ENABLED true Enable cron-triggered queue sweeps
CRON_SCHEDULE 0 2 * * * Cron expression (default: 2 AM daily)

PR Reviewer

Variable Default Description
REVIEWER_ENABLED true Enable automated PR review
REVIEWER_AUTO_REVIEW true Auto-review minion PRs
REVIEWER_AUTO_MERGE false Auto-merge approved PRs
REVIEWER_MERGE_METHOD squash Merge method (squash/merge/rebase)
REVIEWER_MIN_CONFIDENCE 0.8 Minimum confidence to approve

Overlord Meta-Orchestration (Phase 1-3)

overlord.yml

The Overlord daemon and CLI are configured via ~/.atom/overlord.yml:

# Project registry
projects:
  nebulus-core:
    path: ~/projects/nebulus-core
    remote: jlwestsr/nebulus-core
    role: shared-library           # shared-library | platform-deployment | frontend | tooling | provisioning | personal
    branch_model: develop-main     # develop-main | trunk-based | gitflow
    depends_on: []

  nebulus-prime:
    path: ~/projects/nebulus-prime
    remote: jlwestsr/nebulus-prime
    role: platform-deployment
    depends_on: [nebulus-core]

  nebulus-atom:
    path: ~/projects/nebulus-atom
    remote: jlwestsr/nebulus-atom
    role: tooling
    depends_on: [nebulus-core]

# Autonomy levels: cautious | proactive | scheduled
autonomy:
  global: cautious
  overrides:
    nebulus-core: cautious         # Always require approval for shared library
    nebulus-atom: proactive        # Auto-execute low-risk changes
  pre_approved:
    nebulus-atom: [merge, test]    # These actions skip proposal workflow

# Model tiers for dispatch
models:
  local:
    endpoint: http://localhost:5000
    model: llama-3.1-8b
    tier: local
  heavy:
    endpoint: http://gpu-server:8080
    model: qwen3-coder-30b
    tier: heavy

# Daemon scheduler (Phase 3)
schedule:
  scan: "0 * * * *"               # Hourly health check
  test-all: "0 2 * * *"           # Nightly test sweep
  clean-stale-branches:
    cron: "0 3 * * 0"             # Weekly stale branch detection
    enabled: true

# Notification settings (Phase 3)
notifications:
  urgent_enabled: true             # Immediate Slack alerts for critical events
  digest_enabled: true             # Daily digest summary
  digest_cron: "0 8 * * *"        # 8 AM UTC daily

Overlord Environment Variables

Variable Default Description
OVERLORD_STATE_DB /var/lib/overlord/state.db SQLite state database path
OVERLORD_HEALTH_PORT 8080 Health check / API port

Daemon Environment Variables (Phase 3)

The daemon requires Slack tokens to enable Slack integration. Without them, it runs in headless mode (scheduler only, no Slack commands or notifications).

Variable Default Description
SLACK_BOT_TOKEN - Slack Bot OAuth Token (xoxb-...)
SLACK_APP_TOKEN - Slack App-Level Token for Socket Mode (xapp-...)
SLACK_CHANNEL_ID - Channel for Overlord messages and proposals

Schedule Configuration

Schedule tasks use standard cron expressions (5 fields: minute, hour, day-of-month, month, day-of-week):

Task Default Cron Description
scan 0 * * * * Ecosystem health check with proactive detection
test-all 0 2 * * * Test sweep across all projects
clean-stale-branches 0 3 * * 0 Stale branch detection (Sundays)

Tasks can be disabled individually:

schedule:
  scan: "*/30 * * * *"            # Every 30 minutes
  test-all:
    cron: "0 2 * * *"
    enabled: false                 # Disabled

Notification Configuration

Setting Default Description
urgent_enabled true Post critical alerts immediately to Slack
digest_enabled true Send daily digest summary
digest_cron 0 8 * * * When to send the digest (cron expression)

The digest includes: health check counts, detections, proposals created/approved/denied, executions, and test sweeps.

Proposal Settings

Setting Default Description
Proposals DB ~/.atom/overlord/proposals.db SQLite database for proposals
TTL 30 minutes Pending proposals auto-expire
Cleanup interval 5 minutes Background cleanup loop frequency

Logging

Variable Default Description
LOG_LEVEL INFO Log level (DEBUG, INFO, WARNING, ERROR)
LOG_FORMAT console Output format (console or json)
LOG_FILE - Optional log file path

Getting Started

Core System

Nebulus Swarm

Overlord Phase 3

Operations

Clone this wiki locally