Nebula

Nebula

Self-hosted AI agent platform. Create, manage, and orchestrate multiple AI agents backed by persistent CLI sessions with cross-agent communication, custom skills, and scheduled tasks.

Paper: Nebula: Decoupling Agent Identity from Runtime in Multi-Agent LLM Systems (April 2026)

Features

• Multi-agent management — Create agents with distinct roles, knowledge, and tool access. Each agent runs in its own persistent CLI session.
• Cross-agent routing — @mention agents in conversations to pull them into collaborative threads. Agents can reference each other's work.
• Custom skills — Teach agents new capabilities via user-defined skills (API integrations, workflows). Org-wide or agent-specific.
• MCP server support — Connect agents to external tool APIs via Model Context Protocol. Org-wide or per-agent.
• Persistent memory — API-managed agent memory with BM25 search. Agents build knowledge across conversations.
• Scheduled tasks — Cron-based and webhook-triggered task execution. Agents run autonomously on schedule.
• Projects — Multi-agent git coordination with milestones, deliverables, and branch-isolated workspaces.
• Remote agents — Run agents on external machines via WebSocket bridge (desktop app or headless CLI client).
• Multi-backend — Supports Claude Code CLI, OpenCode, Codex CLI, and Gemini CLI as execution backends.
• Secrets vault — Write-only encrypted secrets at org and agent scope. Referenced as {{KEY}} in skills and configs.
• Multi-user / multi-org — Local email/password auth. Each user owns organizations that scope agents, settings, and data.

Quick Start

From Source (macOS / Windows)

git clone https://github.com/reforia/Nebula.git
cd Nebula

npm install
cd frontend && npm install && npm run build && cd ..

# Create .env from the example, then generate an encryption key
cp .env.example .env
echo "NEBULA_ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env

npm start

Open http://localhost:8080 — the setup wizard walks you through creating an admin account and detecting CLI runtimes.

Note: npm install runs a postinstall script that fixes execute permissions on the node-pty spawn helper. If you see posix_spawnp failed errors, run node scripts/postinstall.js manually.

Docker (Linux only)

git clone https://github.com/reforia/Nebula.git
cd Nebula
cp .env.example .env

# Generate an encryption key
echo "NEBULA_ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env

docker compose up -d

Why Linux only? Nebula executes AI agents through CLI runtimes (Claude Code, Codex, Gemini CLI, etc.) that must be installed and authenticated on the same machine. On macOS and Windows, Docker runs inside a Linux VM — CLI runtimes installed on your host are not accessible inside the container. You would need to separately install, authenticate, and maintain the CLIs inside the container, losing access to your host filesystem, existing configurations, and credentials. Running from source avoids this entirely by using your existing CLI installations directly.

Requirements

• Node.js 22+ (if running from source)
• At least one CLI runtime installed on the host (from source) or in the container (Docker):
  • Claude Code (claude) — most actively supported
  • OpenCode (opencode)
  • Codex CLI (codex)
  • Gemini CLI (gemini)

Claude Code is the primary development and testing target. Other runtimes are functional but may have rough edges — issues and PRs welcome.

Feature Highlights

Projects - Multi-Agent Collaboration with Git and External Resources

Template Hub

Multi CLI Runtime Support

Secret Redaction

Auto Session Cleanup

Agent Cross Communications - @Someone pulls them to conversation, @notify Someone tells someone about something

Remote Agent Execution

And many, many more

Layered Memory Management, Soul/Body splition, Org - Agent - Project context aggregation, Webhook, MCP, etc. Full features can be found here

Architecture

Single container: Node.js 22, Express backend, React frontend (served as static), SQLite via better-sqlite3.

User (email/password auth)
 └── Organization
      ├── Agents (each with own CLI session)
      │    ├── Conversations
      │    ├── Tasks (cron / webhook)
      │    ├── Custom Skills
      │    ├── Secrets
      │    ├── MCP Servers
      │    └── Memories
      ├── Projects (multi-agent git coordination)
      ├── Custom Skills (org-wide)
      ├── MCP Servers (org-wide)
      └── Secrets Vault (org-wide)

Configuration

All configuration is via environment variables in .env. The npm scripts load this file automatically via Node's --env-file-if-exists flag, and Docker Compose reads it for container configuration.

cp .env.example .env

Server variables (used by both Docker and from-source)

Variable	Default	Description
NEBULA_ENCRYPTION_KEY	—	Required. AES-256 key for secrets vault. Generate with openssl rand -hex 32.
DATA_DIR	/data	Persistent data directory. Set to ./data when running from source.
PORT	8080	HTTP port the server listens on.
NEBULA_URL	—	External URL of this instance (e.g. http://your-server:8080). Required for remote agents and built-in skills.
AUTH_PROVIDER	local	Auth mode: local (email/password) or enigma (OAuth)
TZ	UTC	Timezone for cron schedules
HTTP_PROXY / HTTPS_PROXY	—	HTTP proxy for outbound requests. NO_PROXY defaults to localhost,127.0.0.1.

Docker-only variables (ignored when running from source)

Variable	Default	Description
NEBULA_PORT	8080	Host port mapped to the container's PORT.
NEBULA_DATA_DIR	./data	Host path mounted as /data inside the container.
RUNTIMES_DIR	./runtimes	Directory for CLI runtime binaries. Place or symlink binaries into runtimes/bin/ — auto-detected at startup.
CLI_HOME_DIR	./cli-home	Persists CLI auth and config (~/.claude, ~/.config/gemini, etc.) across container restarts.
SSH_KEYS_DIR	./ssh-keys	Mounts SSH keys into the container (read-only).
NEBULA_UID / NEBULA_GID	1000	Container user UID/GID — match your host user for correct file ownership.

CLI Runtime Registry

Agents execute via pluggable CLI adapters. No CLI is hardcoded — adding a new runtime is one adapter file + one line of registration. See docs/ADDING_CLI_RUNTIMES.md.

Development

# Backend (reads DATA_DIR from .env)
npm run dev

# Frontend dev server (proxies to backend on :8080)
cd frontend && npm run dev

# Run tests
npm test

Deploying

Docker Compose

docker compose up -d

Custom Server

Use scripts/deploy.sh for tarball-based deployment to a remote server:

NAS_HOST=user@your-server NAS_SSH_PORT=22 bash scripts/deploy.sh

Remote Agent App

Agents can run on external machines, connecting back to Nebula via WebSocket. The Agent App (agent-app/) is a Tauri desktop app for macOS and Windows.

Building

Requires Rust and Tauri prerequisites.

cd agent-app
npm install
npm run tauri dev    # Development
npm run tauri build  # Production binary (.dmg / .msi)

Usage

1. In Nebula web UI, open agent Settings > General > Execution Mode > Remote
2. Click Generate Token and copy it
3. Open the Agent App, paste the server URL, agent ID, and token
4. The app connects via WebSocket and runs the CLI locally on your machine

Security Model

Nebula runs all agents within a single Docker container. The container is the primary isolation boundary — agents cannot access the host filesystem or network beyond what Docker exposes.

What's isolated:

• Agents from the host (Docker container boundary)
• Agent data at rest (secrets encrypted with AES-256-GCM, write-only in UI)
• Inter-agent communication (routed through the platform via @mention, not direct access)
• Session auth errors (detected and surfaced immediately, no silent failures)

Known limitation — shared filesystem within container:

All agents in the same container share the same Linux user and filesystem namespace. An agent could theoretically read another agent's working directory or the SQLite database file. In practice, agents operate within their assigned working directories and interact with peers only through Nebula's routing layer. This is acceptable for single-owner deployments where you control all agents.

If you need stronger isolation:

• Run separate Nebula instances (one per trust boundary)
• Use the remote agent feature to run agents on dedicated machines
• Per-agent filesystem isolation via mount namespaces (bubblewrap) is tracked as a future enhancement

License

AGPL-3.0 — free to use, modify, and self-host. Network use requires source disclosure of modifications.