Architecture

A COS, not a wrapper around a model.

A chatbot UI calls a model and forgets. Nebula-COS puts an owned, contract-first backend between you and the provider — so memory, actions, untrusted content, egress, and backups are yours to inspect and govern. The model is swappable; the trust kernel is the product.

See the honest map → How it's wired →
For builders

A Cognitive OS, not a wrapper

A chatbot UI calls a model and forgets. Nebula-COS puts an owned, contract-first backend between you and the provider — so memory, actions, untrusted content, egress, and backups are yours to inspect and govern.

The model is swappable; the trust kernel is the product. Everything below is described at the level a reader can verify against the repo — file paths, capability flags, and a single-writer ledger, not marketing.

Diagram of the Nebula-COS backend sitting between the user and the model provider, holding memory, actions, content firewall, egress, and backups
The stack

What the backend is made of

Six layers carry a Live tag. The optional lanes sit below them, dimmed and labeled, because they ship gated — never on by default.

Web UI

apps/web static JS — setup wizard plus provider, turn, memory, and backup tabs.

Live
Capabilities contract

/v1/capabilities emits a full feature matrix; nearly all optional features default false.

Live
Chat / turn routing

/v1/turn drives conversation; in-chat tool loops are off by default.

Live
Trust kernel

Memory ledger · action receipts · external-content firewall · backup/restore · egress allowlist · sanitizer.

Live
Provider bridge

Hosted OpenAI-compatible; DeepSeek v4 suggested in the wizard, user-supplied.

Live
Storage

SQLite with schema versioning and corruption recovery.

Live

// optional lanes — shipped gated, off by default

Optional lanes

Voice overlay · local-models overlay · pairing · artifacts.

Optional · off by default
How it's wired

One monorepo, three compose profiles

Monorepo: apps/server (the FastAPI cos package — routes / services / storage / shared layers plus a settings.py env loader), apps/web (the static browser UI), apps/voice-agent (a separate LiveKit worker with pluggable STT/TTS adapters — scaffolded, idle by default), nebula-conformance (a public-API conformance runner plus bounded attestation), and nebula-api (the OpenAPI contract).

Three Docker Compose files keep the default install minimal: compose.yaml (server only, bound to 127.0.0.1:8080), compose.local-models.yaml (opt-in llama.cpp overlay), and compose.voice.yaml (opt-in LiveKit + voice-agent overlay).

The server tells the truth about itself

Live

Contract-first means capabilities.py emits every optional feature as disabled by default, and a single-writer LIVE-CODE-STATUS ledger tracks each surface as live / built / gated / aspirational against file-level evidence.

under the hood: apps/server/cos/…/capabilities.py · LIVE-CODE-STATUS ledger
The honest map

What runs vs. what's gated

The same facts as the Product page, framed for engineers — with the why. We ship the seams, gated, rather than pretend they're done.

Live · shipped + tested Optional · off by default Roadmap · not yet in COS

Live

Live
  • Self-hosted server on 127.0.0.1:8080
  • Capabilities contract (/v1/capabilities)
  • Provider-bridge chat (/v1/turn)
  • Memory ledger (no auto-inject)
  • Action receipts + recovery
  • External-content firewall
  • Egress allowlist + sanitizer
  • Backup / restore
  • SQLite storage + schema versioning

Optional · off

Off by default
  • Voice overlay — the token signer and Parakeet/Kokoro adapters exist, but the overlay ships with STT/TTS URLs empty and JOIN_LIVEKIT=false, so the worker idles.
  • Local-models overlay — opt-in llama.cpp, no bundled model.
  • In-chat tool loops — present, default off.
  • Pairing & artifacts lanes — gated.

Roadmap

Not yet in COS
  • Agentic memory recall — the live ledger deliberately does not auto-inject (turn_context=false); recall is not yet ported.
  • Proactive action proposals.
  • Live voice loop (beyond the idle scaffold).
  • Bundled local inference.

// Voice is scaffolded-not-live: adapters exist, JOIN_LIVEKIT=false, STT/TTS URLs empty → worker idles. // Agentic recall: turn_context=false → the ledger does not auto-inject. Local inference: opt-in, no bundled model.

A live-vs-gated map of every COS surface, color-coded by the same tag system above.
A live-vs-gated map of every COS surface, color-coded by the same tag system above.

Relationship to the broader Nebula

Ecosystem

Nebula-COS is the public Community-Edition port of a private engine (jarvis-nebula) and is faced by a separate mobile/glasses client (Nebula-Android). Those repos carry their own live, gated, and unverified features — and several of their headline capabilities are themselves off by default or on-device-unverified.

They are the broader Nebula roadmap and ecosystem, not Nebula-COS features. This site only claims what ships in COS.

Install Nebula-COS → See what's live →