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)
- Multi-agent management — Create agents with distinct roles, knowledge, and tool access. Each agent runs in its own persistent CLI session.
- Cross-agent routing —
@mentionagents 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.
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 startOpen http://localhost:8080 — the setup wizard walks you through creating an admin account and detecting CLI runtimes.
Note:
npm installruns a postinstall script that fixes execute permissions on thenode-ptyspawn helper. If you seeposix_spawnp failederrors, runnode scripts/postinstall.jsmanually.
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 -dWhy 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.
- 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 (
Claude Code is the primary development and testing target. Other runtimes are functional but may have rough edges — issues and PRs welcome.
Agent Cross Communications - @Someone pulls them to conversation, @notify Someone tells someone about something
Layered Memory Management, Soul/Body splition, Org - Agent - Project context aggregation, Webhook, MCP, etc. Full features can be found here
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)
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| 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. |
| 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. |
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.
# 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 testdocker compose up -dUse scripts/deploy.sh for tarball-based deployment to a remote server:
NAS_HOST=user@your-server NAS_SSH_PORT=22 bash scripts/deploy.shAgents 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.
Requires Rust and Tauri prerequisites.
cd agent-app
npm install
npm run tauri dev # Development
npm run tauri build # Production binary (.dmg / .msi)- In Nebula web UI, open agent Settings > General > Execution Mode > Remote
- Click Generate Token and copy it
- Open the Agent App, paste the server URL, agent ID, and token
- The app connects via WebSocket and runs the CLI locally on your machine
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
AGPL-3.0 — free to use, modify, and self-host. Network use requires source disclosure of modifications.