Deployment

Deployment

Docker Deployment

Core Agent

Build and run the core Nebulus Atom agent:

# Build the image
docker build -t nebulus-atom:latest .

# Run with Docker Compose
docker compose up -d agent

# View logs
docker compose logs -f agent

Flight Recorder Dashboard

docker compose up -d dashboard

Access at http://localhost:8501.

Full Core Stack

docker compose up -d

Starts both the agent and dashboard services.

Swarm Deployment

Build Images

# Overlord image
docker build -t nebulus-overlord:latest -f nebulus_swarm/overlord/Dockerfile .

# Minion image
docker build -t nebulus-minion:latest -f nebulus_swarm/minion/Dockerfile .

Start the Overlord

# Using Docker Compose
docker compose -f docker-compose.swarm.yml up -d overlord

# Or directly
docker run -d \
  --name overlord \
  -p 8080:8080 \
  -v overlord-state:/var/lib/overlord \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --env-file .env.swarm \
  nebulus-overlord:latest

The Overlord needs access to the Docker socket to spawn minion containers.

Verify Health

curl http://localhost:8080/health
# {"status": "ok"}

curl http://localhost:8080/status
# {"paused": false, "active_minions": [], ...}

Swarm Dashboard

OVERLORD_URL=http://localhost:8080 \
STATE_DB_PATH=/path/to/state.db \
streamlit run nebulus_swarm/dashboard/app.py

Network Architecture

┌─────────────────────────────────────────┐
│            nebulus-swarm network         │
│                                         │
│  ┌───────────┐    ┌──────────────────┐  │
│  │  Overlord │    │   Minion(s)      │  │
│  │  :8080    │◄──►│   (ephemeral)    │  │
│  └─────┬─────┘    └────────┬─────────┘  │
│        │                    │            │
└────────┼────────────────────┼────────────┘
         │                    │
         ▼                    ▼
    Docker Socket        LLM Server
   (host mounted)     (external network)

The Overlord and Minions communicate over the nebulus-swarm Docker bridge network. The Overlord exposes port 8080 for external access (health checks, dashboard).

Production Considerations

Persistent State

Mount the state database to a persistent volume:

volumes:
  overlord-state:
    driver: local

Resource Limits

Minion containers are created with:

• 2 GB memory limit
• 1 CPU core
• Auto-cleanup after exit

Monitoring

• Health endpoint: GET /health returns 200 when Overlord is running
• Status endpoint: GET /status returns active minions, config, pending questions
• Docker health check: Configured in docker-compose with 30s intervals

Backup

Back up the SQLite state database regularly:

# Copy from Docker volume
docker cp overlord:/var/lib/overlord/state.db ./backup/state.db

# Or if using a mounted volume
cp /path/to/state.db ./backup/state.db

Log Management

Configure structured logging for production:

LOG_LEVEL=INFO
LOG_FORMAT=json
LOG_FILE=/var/log/overlord/overlord.log

Graceful Shutdown

The Overlord handles SIGTERM gracefully:

1. Stops accepting new work
2. Waits for active minions to finish (or timeout)
3. Saves state to SQLite
4. Exits cleanly

docker compose -f docker-compose.swarm.yml down

Local Development

For development without Docker:

# Core agent
source .venv/bin/activate
python3 -m nebulus_atom.main start

# Swarm dashboard
streamlit run nebulus_swarm/dashboard/app.py

# Run tests
python3 -m pytest tests/ -v

Related Pages

• Installation - First-time setup
• Configuration - Environment variables
• Nebulus Swarm - Swarm architecture
• Troubleshooting - Common deployment issues