docs · install

Install omadia in 60 seconds.

clone → configure → up → open.

Local install runs the full omadia stack on your machine via Docker Compose. One file, seven services, host-bound to 127.0.0.1. No external dependencies beyond an Anthropic API key.

BOOT LOG

$ docker compose up -d

✔ Container omadia-postgres-1 Started
✔ Container omadia-kroki-1 Started
✔ Container omadia-minio-1 Started
✔ Container omadia-ollama-1 Started
✔ Container omadia-presidio-1 Started
✔ Container omadia-middleware-1 Started
✔ Container omadia-web-ui-1 Started

pre-1.0 · public preview

APIs and database schemas may break between minor versions until 1.0.0. The OSS distribution is preview-quality. Fine for evaluation, treat production rollouts as opt-in.

01 · prerequisites

What you need before you start.

Three boxes to tick. The whole stack pulls and boots in roughly 60 seconds on a warm cache.

Docker + Compose

docker engine 24+ · compose v2

Docker Desktop, Colima, OrbStack, or a plain Docker Engine on Linux. Anything that ships `docker compose` v2.

Anthropic API key

collected by the setup wizard

Sign up at console.anthropic.com and grab a key. The setup wizard collects it on first boot and encrypts it into the per-plugin vault. No file edits needed in the happy path.

~4 GB free RAM

postgres + middleware + sidecars

Comfortable headroom for postgres, the middleware, the admin UI, and the four sidecars (kroki, minio, ollama, presidio). The stack idles low after boot.

02 · quickstart

Four steps between clone and the first agent.

Every command is copy-paste from the canonical README. Each step has a single failure mode, with a fix.

Clone

github · MIT-licensed

Grab the OSS distribution from the byte5ai/omadia repository. Default branch is `main`; tagged releases (v0.x.y) are recommended for stable deployments.

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

Up

docker compose up -d

Compose auto-discovers `docker-compose.yaml`. Brings up postgres, the middleware kernel, the admin UI, and all four sidecars on the omadia network. No `.env` file needed in the happy path.

docker compose up -d

Open + setup wizard

http://localhost:3333/setup

The admin UI lands on `/setup` on first boot, unlocked until a user exists. The wizard creates the first administrator and stores your Anthropic API key encrypted into the per-plugin vault. Then `/setup` self-locks (returns 410 Gone) and `/login` takes over.

open http://localhost:3333

(Optional) customize

middleware/.env · power-user only

For headless boots, model overrides, or rotating secrets outside the vault, copy the example file and edit. Most operators never need this. Defaults cover the happy path.

cp middleware/.env.example middleware/.env
$EDITOR middleware/.env   # override defaults (optional)

03 · first boot

Setup wizard does the rest.

On first boot, /setup is unlocked until a user exists. It creates the first administrator and stores your Anthropic API key encrypted into the per-plugin vault. Once an administrator exists, /setup self-locks (returns 410 Gone) and /login takes over.

04 · optional profiles

Modular sidecars for advanced setups.

The root compose ships every sidecar. If you'd rather opt in piece by piece, the `infra/docker-compose.yml` file exposes three named profiles you can mix.

--profile diagrams

Kroki + Mermaid companion + MinIO for the diagrams capability. Rendered Mermaid / Graphviz / PlantUML / Vega-Lite, signed PNG URLs.

docker compose -f infra/docker-compose.yml --profile diagrams up -d

--profile embeddings

Ollama running in-tenant for embeddings. No external API required. Boots a small model for vector retrieval against your knowledge graph.

docker compose -f infra/docker-compose.yml --profile embeddings up -d

--profile privacy-presidio

Microsoft Presidio NER sidecar for the privacy-proxy detector plugin: names, addresses, organisations, DE IDs.

docker compose -f infra/docker-compose.yml --profile privacy-presidio up -d

All three at once: `--profile diagrams --profile embeddings --profile privacy-presidio`. Profiles never break the base stack. Opt-in only.

05 · plugin hub

Install plugins from the Hub.

Once omadia is up, point it at the Hub to discover and install signed plugin ZIPs (channels, integrations, agents). The Hub is the canonical omadia plugin registry; the in-app store mirrors what's published there.

Visit hub.omadia.ai

Pre-1.0: the Hub registers signed omadia-author plugins today; third-party publishing opens at 1.0.

06 · next steps

From boot log to first agent.

Build an agent

The Builder writes the TypeScript, runs the typechecker, and ships a signed ZIP plugin. Live preview while it builds.

Open the Builder

Tune the voice

Kemia exposes twelve persona axes, four boundary categories, and a sycophancy level, bundled and exportable.

Open Kemia

Run a pilot

30-minute call. We open omadia live on a real workflow from your side. You walk away with a draft.

Get in touch