CLI Runtimes#

Nebula doesn't ship its own AI engine. Instead, it uses a pluggable CLI registry — each supported AI CLI tool gets a thin adapter that normalizes its interface for Nebula's execution engine. No CLI is hardcoded; the executor reads adapter properties instead of checking runtime names.

Supported Runtimes#

Runtime detection and status

How Runtimes Work#

When an agent executes a task, Nebula:

1. Resolves the runtime — agent's configured backend → org default → any available CLI that can run the model → error
2. Assembles the context — system prompt, skills, MCP configs, memory titles
3. Spawns a persistent CLI session via node-pty
4. Injects skills either as files on disk or inlined into the system prompt, depending on the adapter
5. Streams output back through WebSocket in real-time

Sessions are persistent — the same CLI process handles multiple messages within a conversation, so the agent retains full context.

Runtime Resolution#

When an agent runs, Nebula picks the runtime using this priority:

1. Agent's explicitly configured backend (if available and can run the selected model)
2. Org default runtime (set in Settings → Runtimes)
3. Any available CLI that supports the agent's model
4. Error if nothing matches

Adding a New Runtime#

Adding a new CLI is one adapter file + one line of registration:

1. Create an adapter in src/backends/ that extends ExecutionBackend
2. Implement the required methods: binary detection, session spawning, message passing, output parsing
3. Register it in src/backends/index.js

// src/backends/index.js
registry.register(new YourNewBackend());

The adapter handles CLI-specific quirks (argument format, output parsing, session management) so the rest of Nebula stays runtime-agnostic.

Note: Runtimes are detected at startup. After installing a new CLI tool, restart the Nebula container or click Re-detect in Settings → Runtimes.