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

omadia-pitch-2-B.mp4

---

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 from a real spreadsheet engine over real rows, rather than the model's token stream. When a specialist agent returns a datasetId, the rows are resolved server-side and never pass through the model.

Optional features

The minimal core is postgres + middleware + admin UI. Diagrams, embeddings, and object storage are off by default. Each is an overlay file you add with -f, which starts the sidecar and switches on the matching plugin.

# Object storage (MinIO): chat attachment ingestion
docker compose -f docker-compose.yaml -f docker-compose.storage.yaml up -d

# Diagram rendering (Kroki). Needs object storage, so add both overlays:
docker compose -f docker-compose.yaml \
  -f docker-compose.storage.yaml -f docker-compose.diagrams.yaml up -d

# In-tenant embeddings (Ollama). First boot pulls nomic-embed-text (~270 MB),
# so it needs network access the first time it starts.
docker compose -f docker-compose.yaml -f docker-compose.embeddings.yaml up -d

# Everything at once
docker compose -f docker-compose.yaml \
  -f docker-compose.storage.yaml -f docker-compose.diagrams.yaml \
  -f docker-compose.embeddings.yaml up -d

Diagram rendering also needs a signing secret. Generate one and add it to middleware/.env as DIAGRAM_URL_SECRET before starting the diagrams overlay: openssl rand -hex 32. The plugin stays inactive until it is set.

Plugin development

Start here: byte5ai/omadia-plugin-starter. A ready-to-fork template for your own omadia plugin. Clone it, fill in your logic against @omadia/plugin-api, and ship.

omadia plugins are self-contained ZIP files that the operator uploads through the admin UI. The platform never trusts external npm registries at runtime; plugins ship node_modules baked in, or use the platform's standard library via @omadia/plugin-api. Two reference plugins are also shipped in-tree as starting points:

• agent-reference-maximum: exercises every capability in the plugin API
• agent-seo-analyst: a smaller, focused tool-only example

The Builder UI walks operators through cloning either reference, slot-filling the differentiating logic, and verifying with the smoke runner before install.

Deployment

• Local / single-tenant: docker compose up, see Quickstart above
• Bring-your-own: the runtime is a stock Node + Postgres app; any host that can run both works (Kubernetes, ECS, plain VM).

Required production secret. The shipped image runs with NODE_ENV=production, which makes VAULT_KEY mandatory at boot; without it the middleware refuses to start (this is intentional; the dev fallback writes the master key into the data volume, which is not safe at rest). Generate one with openssl rand -base64 32 and wire it as a platform secret before the first deploy. The bundled docker-compose.yaml pins NODE_ENV=development so the dev fallback stays available for local docker compose up without configuration; drop that override (and set VAULT_KEY in .env) when you re-use the compose file as a starting point for a non-local deploy.

Status & Roadmap

Status: pre-1.0. Public preview. APIs and database schemas may break between minor versions until 1.0.0. Production use of the OSS distribution is supported but the upgrade path is hand-rolled today; an automated migration runner is on the v1.0 roadmap.

Stability promises are scoped to the documented plugin API only; everything else (database schema, internal service surfaces, admin-UI routes) may evolve without notice until 1.0.0.

Active development tracks:

• Conductor: multi-step composition with a human sign-off path. Landing from branch 005-omadia-conductor; it graduates to a first-class feature once that merges to main.
• Plugin marketplace: discovery and signed-package distribution (post-1.0)
• Multi-tenant hosting: out of scope for v1; a separate fork is planned
• Web-IDE for plugin development: moves the Builder authoring loop into the management UI without round-tripping through ZIP uploads (post-1.0)

License

MIT. Copyright (c) 2026 byte5 GmbH.

Third-party dependency licenses and notices are documented in THIRD_PARTY_NOTICES.md. The dependency tree is free of GPL, AGPL, and SSPL packages; weak-copyleft components (LGPL via sharp-libvips, MPL-2.0 via axe-core / lightningcss / dompurify) are used as documented unmodified dependencies.

Troubleshooting

Port already in use. The core binds 3333 for the admin UI plus the Postgres port. If another process holds one of them, the affected container exits on start. Free the port, or remap it in your own compose override, then re-run docker compose up -d.

VAULT_KEY missing at boot. A production image (NODE_ENV=production) refuses to start without VAULT_KEY, on purpose. Generate one with openssl rand -base64 32 and set it in your project-root .env before deploying. The bundled docker-compose.yaml pins NODE_ENV=development, so a local docker compose up keeps the dev fallback. Full context lives in Deployment.

Optional overlay not found. Optional features are overlay files added with repeated -f flags, not Compose profiles. Pass the full filename, for example -f docker-compose.yaml -f docker-compose.storage.yaml. A bare --profile storage matches nothing here.

Node version mismatch from source. The middleware pins its Node major version in .nvmrc and stops npm install on a different one, because better-sqlite3 and other native modules are compiled against a specific ABI. Run nvm use in the repository root before installing.

Contributing

See CONTRIBUTING.md for the dev setup, commit-message convention, and pull-request workflow. The CODE_OF_CONDUCT.md (Contributor Covenant 2.1) applies to all interactions in issues, pull requests, and discussions.

Security

Found a vulnerability? Please do not open a public issue. See SECURITY.md for the coordinated-disclosure process and the private contact channel.

Maintainership

omadia is maintained by byte5 GmbH under the GitHub organisation byte5ai. Outside contributions are welcome; see CONTRIBUTING.md.