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

• Docker
• moon (task runner)

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:

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>:

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:

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

# 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

• moon
• Docker

Build Commands

# Build the production Docker image
moon run root:image

Environment Variables

Required

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

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.