omadia

An Agentic OS for professionals

Website · Quickstart · Why omadia? · Docs · Contributing

omadia is a self-hostable, multiplayer agentic OS that makes AI dependable enough for real work. A team of agents runs on infrastructure you own and works inside your team's shared channels, so several people collaborate with the same agents in one context, not a private one-on-one chatbot. The agents turn your data, software, and people into results you can steer, audit, and prove. Sensitive data stays in the house and never leaves in clear text. Every answer is checked before it ships. Every action carries a receipt. Bring your own LLM key and switch providers by config, not code.

🎬 The 2-minute pitch

https://github.com/user-attachments/assets/644f9dae-c8a9-44af-a47f-183d2fcdcf34

---

Prerequisites

The quickstart runs entirely in containers, so the host stays light:

• Docker 24+ with the Docker Compose v2 plugin (the docker compose subcommand, not the legacy docker-compose binary)
• Git, to clone the repository

That is the whole list for running omadia. A local Node toolchain is only needed when you build the services from source or develop plugins:

• Node 22.x for the middleware and admin UI outside Docker. The pinned version lives in .nvmrc, so nvm use picks it up. The middleware blocks installation on a mismatched major version, because native modules are built against a specific ABI.

See CONTRIBUTING.md for the full from-source setup.

⚡ Quickstart

git clone https://github.com/byte5ai/omadia.git && cd omadia

# 1. Bring up the minimal core: postgres + middleware + admin UI.
#    Images are pulled prebuilt from GHCR, so first boot is a download,
#    not a source build. No config needed to start.
docker compose up -d

# 2. Open the admin UI and complete the first-admin wizard.
#    The /setup wizard collects your LLM key and stores it encrypted in the vault.
open http://localhost:3333

docker compose up -d pulls exactly three services and nothing else. Open the UI, set your LLM key in the wizard, and run your first agent team. The next section is the 90-second "wow moment". Diagrams, embeddings, and object storage are opt-in (see Optional features).

Pin a specific release instead of the latest with the OMADIA_VERSION shell variable (or a project-root .env file, not middleware/.env), or build the images from source instead of pulling:

OMADIA_VERSION=v0.3.0 docker compose up -d                              # pin a release
docker compose -f docker-compose.yaml -f docker-compose.build.yaml up -d --build  # build locally

Pull fails with manifest unknown? The GHCR images publish on each release, so a brand-new checkout can briefly predate the first published image. Build from source with the --build line above until a release lands.

🚀 First run: from prompt to audit receipt

Describe an agent in plain words → the builder generates it → try it out. No code.

omadia clicks once you watch a team of agents do real work and hand you a receipt for it:

1. Run docker compose up -d. The minimal core (postgres, middleware, admin UI) comes up together.
2. Open http://localhost:3333 and finish the first-admin /setup wizard.
3. Start a demo agent team from a single prompt in the web chat.
4. Watch it work. The orchestrator streams turns and dispatches tools across the agents in the team.
5. Open the run's trace. The per-run call-stack viewer is your audit receipt: every step, every tool call, every decision, replayable.

Why omadia?

omadia is built for the moment an agent system leaves the laptop and meets real work: ownership, auditability, and a clean fit into an existing stack. The first three rows are why teams choose it; the rest is the groundwork done properly.

Capability	What you get
🛡️ Privacy Shield	Raw tool results stay behind a data-plane boundary; the LLM sees only an identity-free digest. guarded by default, with bypass/per_tool opt-in and an org-wide clamp (OMADIA_PRIVACY_FORCE_GUARDED). Real data can run through omadia without running through the model.
✅ Answer verification	A verifier checks each answer's claims against the run's own sources and records a verdict (approved / approved_with_disclaimer) before it reaches the channel.
🧮 Computed, not guessed	Office and Excel output comes from a real spreadsheet engine, server-side, over real rows (datasetId). The figures are calculated by that engine rather than produced by the model.
🧾 A receipt for every action	Every agent run carries a full per-run trace and call-stack viewer: every step, tool call, and decision, replayable.
👥 Multiplayer by design	Agents run in your team's shared channels (Slack, Teams, Telegram, Discord), so several people work with them in one context, not a private one-on-one chatbot.
🤖 Agent teams, not one chatbot	An orchestrator routes each turn to the right specialist plugin agent. Channels, integrations, tools, and capability providers sit behind one stable API.
🔒 Self-hosted and yours	One docker compose up on a single machine. Your Postgres, your LLM key, all of the data on your own infrastructure. GDPR-aware and made in the EU.
🧩 Signed plugin distribution	Plugins ship as verifiable signed packages. The platform never pulls arbitrary npm at runtime.
🔌 Enterprise integrations	Microsoft 365, Odoo, Confluence, Teams, and Telegram, with the LLM provider a swappable plugin.

What's in the box

• Privacy Shield: a data-plane boundary that interns raw tool results and exposes only an identity-free digest to the LLM (harness-plugin-privacy-guard, privacyMode.ts)
• Answer verifier: claim-checks each answer against its sources and returns a verdict before it ships (harness-verifier, verifierService.ts)
• Office compute: create_xlsx / create_docx build real spreadsheets and documents server-side, resolving dataset rows without routing them through the model (harness-plugin-office)
• Plugin runtime: channels, integrations, tools, sub-agents, and capability providers; everything is a plugin behind a stable API surface (@omadia/plugin-api)
• Builder: UI-driven plugin authoring with codegen, slot-typecheck, in-process ESLint auto-fix, and a runtime smoke harness
• Knowledge graph: pgvector-backed (Postgres) with an in-memory alternative for tests
• Channels: web-chat (admin UI) is in-tree; Teams and Telegram ship as separately-distributed plugin ZIPs
• Auth: multi-provider login (local password + OIDC), per-provider user table, admin UI for provider toggle and user management
• Routines: user-authored cron-triggered agent runs with a full per-run trace and call-stack viewer

Design

The operator UI speaks Lume, omadia's own visual language. The idea is that light is the material: surfaces read as condensed out of light, and the agent's attention shows up as accent-tinted illumination, not as flat color. Four recipes carry it. Surfaces are gradient pairs, borders catch the light on their top edge, one accent slot glows to mark focus and selection, and corners stay soft.

Three accent palettes ship, Petrol, Atelier, and Lagoon as the default. The operator picks one and switches between light and dark from the header. The whole theme lives in a single token file (web-ui/app/_lib/theme.css), so restyling stays a change at the token tier rather than a sweep through components.

Lume is specified in byte5ai/omadia-ui under docs/visual-spec.md, the same language omadia's canvas app is built on. The operator UI and the canvas app share one identity.

Architecture

         ┌────────────────────────────────────────────────────────────┐
         │                       Channels                             │
         │  web-chat   Teams   Telegram   …                           │
         └────────────────────┬───────────────────────────────────────┘
                              │  ChannelSDK (SemanticAnswer)
                              ▼
         ┌────────────────────────────────────────────────────────────┐
         │                      Orchestrator                          │
         │  routes turns to agents, manages tool dispatch, streaming  │
         └────────────────────┬───────────────────────────────────────┘
                              │  ctx (PluginContext)
                              ▼
         ┌────────────────────────────────────────────────────────────┐
         │                        Plugins                             │
         │  agents  ·  tools  ·  capability providers  ·  integrations│
         └────────────────────┬───────────────────────────────────────┘
                              │
        ┌─────────────────────┴────────────────────────────┐
        ▼                     ▼                            ▼
  Knowledge Graph       Embeddings                  Vault (secrets)
  (Postgres + pgvector) (Ollama / API)              (AES-256-GCM file)

Start with the architecture overview for the component map and request flow. The deeper walk-through of the plugin loading sequence, capability registry, and multi-provider authentication layer lives under docs/.

Trust & privacy architecture

Three subsystems let omadia put real data in front of an LLM and stand behind the answer:

• Privacy Shield (data-plane boundary): raw tool results are interned behind the boundary and the LLM sees only an identity-free digest. guarded is the default; bypass and per_tool are explicit opt-ins, and OMADIA_PRIVACY_FORCE_GUARDED clamps every plugin to guarded org-wide. Pseudonyms resolve back to real values only at materialization, and each bypass lands in the receipt. Spec: specs/001-privacy-shield-v4/.
• Answer verification: before a turn's answer is returned, the verifier checks its claims against the run's sources and emits a verdict (approved, approved_with_disclaimer, or blocked). A borderline verdict attaches a disclaimer instead of silently shipping an unsupported claim.
• Office compute (computed, not guessed): numbers in .xlsx / .docx output come f