Nebulus Swarm

Nebulus Swarm

Nebulus Swarm is a multi-agent orchestration system that autonomously processes GitHub issues and manages cross-project ecosystems. An Overlord receives work requests via Slack or cron schedules, spawns containerized Minion agents that clone repos, work on issues, create PRs, and report results back. In daemon mode (Phase 3), the Overlord runs as a persistent background process with scheduled health checks, proactive detection, approval workflows, and daily digest notifications.

Architecture

┌──────────┐     Slack      ┌──────────────┐     Docker    ┌──────────────┐
│  Human   │ ──────────────→│   Overlord   │──────────────→│   Minion 1   │
│  (Slack) │ ←──────────────│              │               │  (Container) │
└──────────┘   Notifications│  - SlackBot  │               └──────┬───────┘
                            │  - State DB  │                      │
┌──────────┐    Cron/API    │  - Docker    │     Docker    ┌──────┴───────┐
│  GitHub  │ ←─────────────→│  - Queue     │──────────────→│   Minion 2   │
│  Issues  │    Labels/PRs  │  - Router    │               │  (Container) │
└──────────┘                │  - Reviewer  │               └──────────────┘
                            └──────┬───────┘
                                   │
                            ┌──────┴───────┐
                            │  Dashboard   │
                            │ (Streamlit)  │
                            └──────────────┘

Components

Component	Description	Details
Overlord	Control plane	Slack integration, Docker management, state tracking
Overlord Daemon	Background mode	Scheduled sweeps, proactive detection, notifications
Slack Commands	Multi-project router	status, scan, merge, release, autonomy, memory, help
Proposal Manager	Approval workflows	Slack thread-based approve/deny with auto-expiry
Detectors	Proactive monitoring	Stale branches, ahead-of-main, failing tests
Notifications	Alert routing	Urgent alerts + daily digest with category tracking
Minion	Worker agent	Clones repos, works on issues, creates PRs
Model Router	LLM selection	Routes tasks to appropriate models by complexity
Dashboard	Monitoring UI	Streamlit web app with live status and analytics
PR Reviewer	Code review	Automated review of minion-created PRs

Quick Start

1. Configure Environment

cp .env.swarm.example .env.swarm

Edit .env.swarm with your credentials:

# Slack
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token
SLACK_CHANNEL_ID=C0123456789

# GitHub
GITHUB_TOKEN=ghp_your_token
GITHUB_WATCHED_REPOS=owner/repo1,owner/repo2

# LLM
NEBULUS_BASE_URL=http://192.168.4.30:8080/v1
NEBULUS_MODEL=qwen3-coder-30b

2. Build and Start

# Build images
docker build -t nebulus-overlord:latest -f nebulus_swarm/overlord/Dockerfile .
docker build -t nebulus-minion:latest -f nebulus_swarm/minion/Dockerfile .

# Start Overlord
docker compose -f docker-compose.swarm.yml up -d overlord

3. Issue a Command via Slack

In your configured Slack channel:

work on owner/repo#42

The Overlord spawns a Minion, which clones the repo, reads the issue, implements a solution, creates a PR, and reports back.

Workflow

1. Issue labeled "nebulus-ready" on GitHub
       ↓
2. Overlord detects issue (cron sweep or Slack command)
       ↓
3. Model Router analyzes complexity → selects model
       ↓
4. Docker spawns Minion container with selected model
       ↓
5. Minion: clone → branch → read issue → work → test → PR
       ↓
6. PR Reviewer examines the PR (if enabled)
       ↓
7. Minion reports completion → Overlord notifies Slack
       ↓
8. Human reviews and merges

Slack Commands

Minion Commands (Phase 0)

Command	Description
work on owner/repo#42	Spawn a minion to work on an issue
stop minion-abc123	Kill a running minion
status	Show active minions and system health
pause	Pause queue processing
resume	Resume queue processing
queue	Show pending issues

Natural language variants are also supported via the LLM command parser:

• "can you take a look at issue 42?"
• "what's the status of the swarm?"
• "stop all minions"

Overlord Commands (Phase 3)

When running in daemon mode, @atom mentions route through the SlackCommandRouter:

Command	Description
@atom status [project]	Ecosystem or single project health
@atom scan [project]	Deep scan with proactive detection
@atom merge <project> <src> to <tgt>	Propose a merge (approval required)
@atom release <project> <version>	Coordinated release workflow
@atom autonomy [level]	Show or change autonomy level
@atom memory <query>	Search cross-project observations
@atom approve <id>	Approve a pending proposal
@atom deny <id>	Deny a pending proposal
@atom help	List all commands

Proposals are posted to Slack with scope summaries. Reply "approve" or "deny" in the thread to control execution. Proposals auto-expire after 30 minutes.

GitHub Labels

The Overlord manages issue lifecycle through labels:

Label	Meaning
nebulus-ready	Issue is ready for automated work
in-progress	A minion is actively working on it
in-review	PR created, awaiting review
needs-attention	Minion failed, human review needed
high-priority	Processed before normal priority

Daemon Mode (Phase 3)

The Overlord can run as a persistent background daemon with scheduled sweeps. Full lifecycle management via CLI:

nebulus-atom overlord daemon start     # Launch (refuses if already running)
nebulus-atom overlord daemon status    # Check running state and PID
nebulus-atom overlord daemon stop      # Graceful SIGTERM + wait
nebulus-atom overlord daemon restart   # Stop + start

Scheduled tasks (configurable via overlord.yml):

• scan — Hourly ecosystem health check with proactive detection
• test-all — Nightly test sweep across all projects
• clean-stale-branches — Weekly stale branch detection

Proactive detection runs automatically during scans:

• Stale branches with no activity for N days
• Develop branches ahead of main with unmerged commits
• Projects with failing or missing tests

Notifications are routed by urgency:

• Urgent — Immediate Slack post for critical events
• Buffered — Accumulated into a daily digest with health checks, detections, proposals, and executions

See Swarm Overlord and Overlord CLI for full details.

Related Pages

• Swarm Overlord - Control plane details
• Swarm Minion - Worker agent details
• Model Router - Multi-LLM routing
• Swarm Dashboard - Monitoring UI
• Configuration - Environment variables
• Deployment - Docker deployment guide