Installation

Installation

Prerequisites

• Python 3.12+
• Git
• A local LLM server running an OpenAI-compatible API (Nebulus Prime, Nebulus Edge, Ollama, TabbyAPI, vLLM, etc.)
• Docker (required for Nebulus Swarm)
• Slack workspace (required for Swarm Overlord)

Clone the Repository

git clone git@github.com:jlwestsr/nebulus-atom.git
cd nebulus-atom

Set Up Python Environment

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

For development (includes testing and linting tools):

pip install -r requirements-dev.txt

Configure Environment

Copy the example environment file and edit it:

cp .env.example .env

Edit .env with your LLM server details:

NEBULUS_BASE_URL=http://localhost:5000/v1    # Your LLM server URL
NEBULUS_API_KEY=admin                         # API key (if required)
NEBULUS_MODEL=Meta-Llama-3.1-8B-Instruct-exl2-8_0  # Your model name
NEBULUS_TIMEOUT=300                           # Request timeout in seconds
NEBULUS_STREAMING=true                        # Enable streaming responses

See Configuration for all available environment variables.

Verify Installation

# Run the test suite
python3 -m pytest tests/ -v

# Start the agent
python3 -m nebulus_atom.main start

You should see the Nebulus Atom prompt. Type help or /help to see available commands.

Install Pre-commit Hooks

The project uses ruff for linting and formatting via pre-commit hooks:

pre-commit install

LLM Server Setup

Nebulus Atom requires a local LLM server with an OpenAI-compatible API. Supported servers:

Server	URL	Notes
Nebulus Prime	http://localhost:5000/v1	Linux — Docker Compose, TabbyAPI/ExLlamaV2, NVIDIA GPU
Nebulus Edge	http://localhost:5000/v1	macOS — bare-metal MLX, Apple Silicon
Ollama	http://localhost:11434/v1	Easy setup, cross-platform
TabbyAPI	http://localhost:5000/v1	ExLlamaV2 backend
vLLM	http://localhost:8000/v1	High throughput

Note: Nebulus Prime and Nebulus Edge are companion projects that provide turnkey local LLM infrastructure. Prime targets Linux with NVIDIA GPUs; Edge targets macOS with Apple Silicon. Either will give you a fully configured OpenAI-compatible server for Nebulus Atom.

The server must support the /v1/chat/completions endpoint with tool calling.

Swarm Installation

For Nebulus Swarm (multi-agent system), additional setup is required. See Nebulus Swarm for details.

Next Steps

• Quick Start - Get running in 5 minutes
• CLI Reference - Learn the available commands
• Configuration - Customize your setup