智能工作流

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.

not a source build. No config needed to start.

docker compose up -d

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](#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:

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.

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.

⚡ Quickstart

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

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.

```bash

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.

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.