Imbi
Imbi is a DevOps Service Management Platform for managing large environments containing many services and applications. It provides a centralized service catalog with metadata management, dependency tracking, ownership hierarchy, and AI-powered features.
Features
- Service Catalog: Centralized inventory of all services and applications
- Dependency Tracking: Graph-based dependency visualization using PostgreSQL + Apache AGE
- Blueprint System: Customizable metadata schemas for extending project fields
- Ownership Hierarchy: Organization, team, and user-based ownership model
- AI Assistant: Conversational AI powered by Claude for service queries
- MCP Server: Model Context Protocol server for AI agent access
- Webhook Gateway: Inbound event processing from GitHub, PagerDuty, etc.
- Scheduled Tasks: Cron, interval, and one-shot triggers that call the API or the gateway as a service account, with run history in ClickHouse
- Analytics: Operations logs and time-series data via ClickHouse
- Authentication: OAuth2/OIDC (Google, GitHub, Keycloak) + local auth
Architecture
+--------------------+
| Caddy |
| reverse proxy |
+--------------------+
|
+---------+-------------+---------+----+-----------+-------------+
| | | | | |
imbi-ui imbi-api imbi-assistant imbi-gateway imbi-mcp imbi-scheduler
(React) (FastAPI) (FastAPI) (FastAPI) (FastMCP) (FastAPI)
| | | | | |
+---------+-------------+---------+----+-----------+-------------+
|
imbi-common
(shared Python library)
|
+-----------------------+
| |
PostgreSQL + AGE ClickHouse
(graph database) (analytics)
imbi-slackbot runs alongside these, connecting out to Slack over socket
mode rather than being proxied.
All services run behind Caddy, a powerful and extensible reverse proxy with automatic HTTPS. The Docker image packages everything into a single deployable unit that can run all services together or scale out individual components.
Quick Start
Prerequisites
Running with Docker Compose
The included compose.yaml starts Imbi and all backing services:
# Build and start everything
docker compose up --build -d
# Run initial setup (create admin user, seed permissions)
docker compose exec -it imbi imbi-api setup
# View logs
docker compose logs -f imbi
Once running, Imbi is available at http://localhost:8080 — the only service published on a fixed host port:
| Service | URL | Description |
|---|---|---|
| Imbi | http://localhost:8080 | Main application (UI + API via Caddy) |
The backing services are exposed on ephemeral host ports (assigned by
Docker) to avoid collisions. Find a service's mapped port with
docker compose port <service> <container-port>:
| Service | Container port | Description |
|---|---|---|
| PostgreSQL | 5432 | Graph database (Apache AGE); user postgres, password secret |
| ClickHouse | 8123 | Analytics database HTTP interface |
| Iggy | 8090 | Apache Iggy message streaming (TCP); user iggy, password iggy |
| Iggy connect | 8081 | Iggy connectors runtime, draining each stream into ClickHouse |
| Mailpit | 8025 | Email testing UI (captures all outbound email) |
| Ministack | 4566 | S3-compatible object storage |
The iggy service sets IGGY_SYSTEM_SHARDING_PIN_CORES=false. Iggy pins
each shard's memory to a NUMA node by default, which Docker Desktop does
not allow — without the flag the server aborts at boot with
MemoryAffinityFailed … BindingFailed for every shard. It also needs
seccomp:unconfined, since the runtime is built on io_uring.
UI Development with Docker Compose
You can use Docker Compose to run the full backend stack while developing the UI locally with hot-reload:
# 1. Start the backend services
docker compose up --build -d
# 2. Run initial setup (first time only — creates admin user, seeds permissions)
docker compose exec -it imbi imbi-api setup
# 3. In the ui/ directory, point the dev proxy at the local backend
cd ui
echo 'VITE_API_URL=http://localhost:8080/api' > .env.local
npm install
npm run dev
The Vite dev server starts on http://localhost:5173 and proxies /api
requests to the Caddy reverse proxy at :8080, which routes them to the
appropriate backend service.
Useful services during UI development:
| Service | URL | Use |
|---|---|---|
| UI (dev) | http://localhost:5173 | Vite dev server with hot-reload |
| Imbi (backend) | http://localhost:8080 | Full app via Caddy (API + bundled UI) |
Mailpit (email) and PostgreSQL (graph data) are reachable on the ephemeral
host ports reported by docker compose port <service> <container-port>
(see the table above) for inspecting state during development.
Python Development
The repository is a uv workspace: every library, app, and plugin is a workspace member sharing one lockfile and one virtualenv. moon is the task runner — it owns the lint/format/typecheck/test/build/docs tasks and downloads its toolchains (node, npm) on first use.
Development prerequisites:
- moon — the version is pinned in
.prototools(proto users get it automatically) - uv — provisions Python 3.14 and the
shared
.venv - Docker — backing services for the test suite
moon run root:setup # uv sync + pre-commit hooks
moon run root:coverage # full suite (single session, aggregate coverage)
moon run api:test # one member's suite in isolation
uv run --env-file .env.test pytest apps/api/tests/endpoints/test_projects.py # a single suite or file
moon run :lint :typecheck :format # ruff + basedpyright across every project
uv run pre-commit run --all-files # reformat (ruff + tombi, write mode)
moon run <member>:test boots the backing services and writes .env.test
first; run moon run root:services yourself before invoking pytest
directly. moon query tasks lists every available task.
Running the Docker Image
# Run all services (default)
docker run -p 8080:8080 \
-e CLICKHOUSE_URL=clickhouse+http://default:password@clickhouse:8123/imbi \
-e POSTGRES_URL=postgresql://postgres:secret@postgres/imbi \
-e IMBI_AUTH_JWT_SECRET=your-secret-here \
-e IMBI_AUTH_ENCRYPTION_KEY=your-encryption-key \
-e IMBI_API_URL=http://localhost:8080/api \
-e VITE_API_URL=http://localhost:8080/api \
ghcr.io/aweber-imbi/imbi:latest
# Run a specific service only
docker run -e IMBI_SERVICE=api ...
docker run -e IMBI_SERVICE=assistant ...
docker run -e IMBI_SERVICE=gateway ...
docker run -e IMBI_SERVICE=mcp ...
docker run -e IMBI_SERVICE=slackbot ...
docker run -e IMBI_SERVICE=scheduler ... # also needs the vars below
docker run -e IMBI_SERVICE=ui ... # Caddy only; set IMBI_*_UPSTREAM
# Run initial setup (create admin user, seed permissions)
docker run -it \
-e CLICKHOUSE_URL=clickhouse+http://default:password@clickhouse:8123/imbi \
-e IMBI_AUTH_JWT_SECRET=your-secret-here \
-e IMBI_AUTH_ENCRYPTION_KEY=your-encryption-key \
ghcr.io/aweber-imbi/imbi:latest setup
Deploying with Helm
helm install imbi helm/imbi \
--set auth.jwtSecret=your-secret \
--set auth.encryptionKey=your-key
See Helm chart documentation for full configuration.
Building
Prerequisites
Build Commands
# Build the production Docker image
moon run root:image
Environment Variables
Required
| Variable | Description | Services |
|---|---|---|
CLICKHOUSE_URL |
ClickHouse connection URL | all |
IGGY_URL |
Iggy connection URL | all |
IMBI_AUTH_JWT_SECRET |
JWT signing secret | all |
IMBI_AUTH_ENCRYPTION_KEY |
Fernet encryption key | all |
IMBI_INTERNAL_API_URL |
Bare origin the scheduler connects to imbi-api on (e.g. http://imbi-api:8000) |
scheduler |
IMBI_SCHEDULER_SA_CLIENT_ID |
Client id of the scheduler's service account | scheduler |
IMBI_SCHEDULER_SA_CLIENT_SECRET |
Client secret of the scheduler's service account | scheduler |
POSTGRES_URL |
PostgreSQL connection URL | all |
In all mode the scheduler is optional: without the service-account
credentials it is simply not started. In scheduler mode they are required —
the account is not seeded, so create a service account in the UI, grant it the
scheduled_task:* permissions plus whatever its tasks need, and issue it a
client credential. See
Scheduler configuration.
Optional
| Variable | Description | Default |
|---|---|---|
IMBI_SERVICE |
Service to run (all, api, assistant, gateway, mcp, scheduler, slackbot, ui) |
all |
IMBI_<SERVICE>_UPSTREAM |
ui mode only: host:port Caddy proxies to for API, MCP, ASSISTANT, GATEWAY, SCHEDULER |
127.0.0.1:<port> |
IMBI_API_URL |
Public URL of the API, including the path prefix it is mounted under (e.g. http://localhost:8080/api); needed when serving behind the bundled Caddy |
- |
VITE_API_URL |
Same value as IMBI_API_URL; injected into the UI at serve time |
- |
ANTHROPIC_API_KEY |
Anthropic API key for assistant | - |
IMBI_ASSISTANT_ENABLED |
Enable the AI assistant | false |
IMBI_EMAIL_ENABLED |
Enable email notifications | false |
IMBI_EMAIL_SMTP_HOST |
SMTP server host | localhost |
IMBI_EMAIL_SMTP_PORT |
SMTP server port | 587 |
IMBI_EMAIL_SMTP_USE_TLS |
Use TLS for SMTP | true |
IMBI_ENVIRONMENT |
Runtime environment | development |
IMBI_IGGY_CONNECTORS_API_KEYS |
Bearer keys the Iggy connectors runtime authenticates with, comma-separated; read by imbi-api only. Unset, that endpoint answers 503 | - |
IMBI_SCHEDULER_API_PREFIX |
Path the scheduler mounts its routes under (/status is never prefixed) |
/api |
IMBI_SCHEDULER_SCHEMA |
Postgres schema holding task definitions | scheduler |
IMBI_GATEWAY_URL |
imbi-gateway base URL for gateway targets |
http://localhost:8003 |
IMBI_SCHEDULER_MAX_CONCURRENT_RUNS |
Per-process ceiling on runs in flight | 20 |
IMBI_SCHEDULER_POLL_INTERVAL |
Upper bound in seconds on the trigger loop's sleep | 30 |
The scheduler has more settings than these; see Scheduler configuration for the full set.
Project Structure
The repository is a monorepo organized as a uv workspace. Every Python
package publishes its own distribution; the root imbi package is a
meta-distribution that installs the whole platform.
imbi/
├── libraries/
│ └── common/ # imbi-common — shared library (imbi.common)
│ └── {pyproject.toml, src/, tests/} # every member carries its own tests
├── apps/
│ ├── api/ # imbi-api — core REST API (imbi.api)
│ ├── assistant/ # imbi-assistant — AI assistant (imbi.assistant)
│ ├── gateway/ # imbi-gateway — webhook gateway (imbi.gateway)
│ ├── mcp/ # imbi-mcp — MCP server (imbi.mcp)
│ ├── scheduler/ # imbi-scheduler — scheduled task triggering
│ │ # (imbi.scheduler)
│ └── slackbot/ # imbi-slackbot — Slack bot (imbi.slackbot)
├── plugins/ # imbi-plugin-* — first-party plugins (imbi.plugins.*)
│ ├── aws/ github/ google/ logzio/ oidc/ pagerduty/ sonarqube/
├── ui/ # React frontend (npm, not a uv member)
├── docs/ # unified Zensical site
├── pyproject.toml # workspace root + the `imbi` meta-package
├── container/ # Dockerfile, Caddyfile, and entrypoint.sh for
│ # the production image
├── compose.yaml # Local run of the production image
├── compose.ci.yaml # Backing services for the test suites
├── helm/imbi/ # Helm chart for Kubernetes deployment
└── .moon/ + moon.yml # moon task runner configuration (lint/test/build/…)
Documentation
Full documentation is available at aweber-imbi.github.io/imbi and covers installation, configuration, administration, and usage.
License
BSD 3-Clause License. See LICENSE for details.
1 maintainer
Release files for imbi 2.32.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| imbi-2.32.0.tar.gz | 3.2 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| imbi-2.32.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 3.2 MB
Release files / imbi-2.32.0.tar.gz
| Download URL | imbi-2.32.0.tar.gz |
|---|---|
| Size | 3.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6e2c9c9b40869cfa850219a48db6ce96ad0bfee2881b0cc3ee01b86e89f9ea4f
|
|
BLAKE2b-256 checksum How to use checksums |
8766e7e5d4a9284a53bf5db4f45133700e55cddceb13e08f214b180409c66500
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 9, 2026.
Transparency logRelease files / imbi-2.32.0-py3-none-any.whl
| Download URL | imbi-2.32.0-py3-none-any.whl |
|---|---|
| Size | 7.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
96a7227d495c116991983d92d26b72ef47415dd8a478769fee662abf0b79c503
|
|
BLAKE2b-256 checksum How to use checksums |
7e16af1d396fad251eb9197e8fd3da94c654026eee740f9d3bcc98441408c2c6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 9, 2026.
Transparency log
