Observal

Discover, share, and monitor AI coding agents with full observability built in.

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.

Documentation

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.

Quick start

Install the CLI (standalone binary, no Python required):

curl -fsSL https://raw.githubusercontent.com/BlazeUp-AI/Observal/main/install.sh | bash

Or install via Python: uv tool install observal-cli / pipx install observal-cli / pip install --user observal-cli. See Installation for details.

Start the server:

curl -fsSL https://raw.githubusercontent.com/BlazeUp-AI/Observal/main/install-server.sh | bash

Or manually:

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

Log in:

observal auth login            # auto-creates admin on fresh server

Eight services start (API, web UI, Postgres, ClickHouse, Redis, worker, OTEL collector, Grafana). Full walkthrough in Quickstart; operator guide in Self-Hosting.

Already have MCP servers in your IDE? Discover and instrument them:

observal scan                                # discover what's installed across your IDEs
observal doctor patch --all --all-ides       # instrument everything (hooks + shims + OTel)
observal pull <agent> --ide cursor           # install a complete agent

scan is read-only -- it shows what you have without modifying anything. doctor patch does the actual instrumentation: wrapping MCP servers with observal-shim for telemetry, installing hooks, and configuring OTel export. A timestamped backup is created automatically before any file is modified.

Supported IDEs

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.

Tech stack

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)

Contributing

See CONTRIBUTING.md. The short version:

1. Fork and clone
2. make hooks to install pre-commit hooks
3. Create a feature branch
4. Run make lint and make test
5. Open a PR

See AGENTS.md for internal codebase context.

Running tests

make test      # quick
make test-v    # verbose

All tests mock external services. No Docker needed.

Community

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.

Security

To report a vulnerability, please use GitHub Private Vulnerability Reporting or email contact@blazeup.app. Do not open a public issue. See SECURITY.md.

License

Apache License 2.0. See LICENSE.

Star history