If you find Observal useful, please consider giving it a star. It helps others discover the project and keeps development going.Observal is a self-hosted AI agent registry with built-in observability. Think Docker Hub, but for AI coding agents.
Browse agents created by others, publish your own, and pull complete agent configurations — all defined in a portable YAML format that templates out to Claude Code, Kiro CLI, Cursor, Gemini CLI, and more. Every agent bundles its MCP servers, skills, hooks, prompts, and sandboxes into a single installable package. One command to install, zero manual config.
Every interaction generates traces, spans, and sessions that flow into a telemetry pipeline. The built-in eval engine scores agent sessions so you can measure performance and make your agents better over time.
Full docs live at observal.gitbook.io (sourced from /docs in this repo).
| Start here | Go to |
|---|---|
| 5-minute install and first trace | Quickstart |
| Understand the data model | Core Concepts |
| Instrument your existing MCP servers | Observe MCP traffic |
| Run Observal on your infrastructure | Self-Hosting |
| Look up a CLI command | CLI Reference |
See CHANGELOG.md for recent updates.
git clone https://github.com/BlazeUp-AI/Observal.git
cd Observal
cp .env.example .env
docker compose -f docker/docker-compose.yml up --build -d
uv tool install --editable .
observal auth login # auto-creates admin on fresh serverEight services start (API, web UI, Postgres, ClickHouse, Redis, worker, OTEL collector, Grafana). Full walkthrough in Quickstart; operator guide in Self-Hosting → Docker Compose setup.
Already have MCP servers in your IDE? Instrument them in one command:
observal scan # auto-detect, register, and instrument everything
observal pull <agent> --ide cursor # install a complete agentThis detects MCP servers from your IDE config files and wraps them with observal-shim for telemetry without breaking your existing setup. A timestamped backup is created automatically. Everything happens locally — nothing is uploaded to the server.
| IDE | Support |
|---|---|
| Claude Code | Full — skills, hooks, MCP, rules, OTLP telemetry |
| Kiro CLI | Full — superpowers, hooks, MCP, steering files, OTLP telemetry |
| Gemini CLI | Native OTEL + shim telemetry |
| Codex CLI | Native OTEL + shim telemetry |
| GitHub Copilot | Shim telemetry |
| OpenCode | Shim telemetry |
| Cursor | MCP + shim telemetry |
Compatibility matrix and per-IDE setup: Integrations.
| Component | Technology |
|---|---|
| Frontend | Next.js 16, React 19, Tailwind CSS 4, shadcn/ui, Recharts |
| Backend | Python 3.11+, FastAPI, Strawberry GraphQL, Uvicorn |
| Databases | PostgreSQL 16 (registry), ClickHouse (telemetry) |
| Queue | Redis + arq |
| CLI | Python, Typer, Rich |
| Eval engine | AWS Bedrock / OpenAI-compatible LLMs |
| Telemetry | OpenTelemetry Collector |
| Deployment | Docker Compose (8 services) |
See CONTRIBUTING.md. The short version:
- Fork and clone
make hooksto install pre-commit hooks- Create a feature branch
- Run
make lintandmake test - Open a PR
See AGENTS.md for internal codebase context.
make test # quick
make test-v # verboseAll tests mock external services. No Docker needed.
Have a question, idea, or want to share what you've built? Head to GitHub Discussions. Please use Discussions for questions; open Issues for confirmed bugs and concrete feature requests.
Join the Observal Discord to chat directly with the maintainers and other community members.
To report a vulnerability, please use GitHub Private Vulnerability Reporting or email contact@blazeup.app. Do not open a public issue. See SECURITY.md.
Apache License 2.0. See LICENSE.