智能工作流

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.

⚠️ Deploying anywhere other than local docker compose up? The shipped image runs with NODE_ENV=production, and since v0.115 the middleware refuses to boot unless two secrets are set: VAULT_KEY and CREDENTIAL_KEYCHAIN_KEY (each openssl rand -base64 32, two different values, never rotated casually). The Render blueprint and fly/deploy.sh generate both; on a self-managed host set them yourself before first boot. Missing either one fails the boot health gate, and on an existing instance the rolling updater then rolls back to the previous version. See Deployment and Troubleshooting.

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.

No Docker? Let your AI assistant install it

Prefer not to touch a terminal? If you have the Claude desktop app (or another AI assistant that can run commands on your machine, such as Codex), paste the prompt below into a chat. The assistant fetches a public skill file and installs the native omadia desktop app (no Docker, no build tools) from the newest GitHub Release that has a build for your OS, then opens the onboarding wizard for you.

Install omadia on my machine by following this skill file, step by step:
https://raw.githubusercontent.com/byte5ai/omadia/main/docs/onboarding/SKILL.md

On a Claude Pro/Max subscription you can pick the CLI-subscription provider in the wizard instead of a metered API key — provided the claude CLI is installed and signed in on the same machine (omadia detects it there). Otherwise the API-key option always works. See docs/onboarding/SKILL.md for exactly what it runs.

Deployment

- Local / single-tenant: docker compose up, see Quickstart above - One-click cloud: deploy the minimal core into your own Render workspace — render.yaml provisions the middleware, admin UI, and Postgres (pgvector), generates VAULT_KEY and CREDENTIAL_KEYCHAIN_KEY, and the /setup wizard collects your LLM key on first boot. Runs on paid instance types (the middleware needs a persistent disk).

- One-command Fly.io: Fly has no blueprint-style deploy button, so the equivalent is one command. fly/deploy.sh provisions three apps in your Fly org — middleware (persistent /data volume), admin UI, and a private pgvector/pgvector Postgres (the same image the compose stack uses; Fly's own Postgres offerings either lack pgvector or gate it behind a dashboard toggle) — generates VAULT_KEY, CREDENTIAL_KEYCHAIN_KEY and the database password, and deploys the GHCR images. Needs a logged-in flyctl; roughly $10/month:

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

- Bring-your-own: the runtime is a stock Node + Postgres app; any host that can run both works (Kubernetes, ECS, plain VM).

Required production secrets. The shipped image runs with NODE_ENV=production, which makes two keys mandatory at boot: VAULT_KEY (secret vault) and, since v0.115, CREDENTIAL_KEYCHAIN_KEY (credential keychain — a separate trust domain, so a separate key). Without either the middleware refuses to start (this is intentional; the dev fallback writes the master keys into the data volume, which is not safe at rest). Generate each with openssl rand -base64 32 and wire both as platform secrets before the first deploy. Upgrading an existing instance from a version older than v0.115? Add CREDENTIAL_KEYCHAIN_KEY before pulling the new image, or the boot health gate fails and the rolling updater rolls back. 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 or CREDENTIAL_KEYCHAIN_KEY missing at boot. A production image (NODE_ENV=production) refuses to start without both keys, on purpose (CREDENTIAL_KEYCHAIN_KEY is required when NODE_ENV=production is the message since v0.115). Generate each with openssl rand -base64 32 and set them as secrets before deploying.

Update rolled back with health gate failed: never_reachable. The new image never answered /health within the gate window, so the updater restored the previous version — the instance keeps running. The most common cause is a secret the new version requires at boot that the old one did not, above all CREDENTIAL_KEYCHAIN_KEY when coming from a version older than v0.115. Check the middleware logs from the failed boot right away (hosted log retention is short), add the missing secret, and re-run the update. 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.