██████╗ ██████╗ ███████╗███████╗██████╗ ██╗   ██╗ █████╗ ██╗
██╔═══██╗██╔══██╗██╔════╝██╔════╝██╔══██╗██║   ██║██╔══██╗██║
██║   ██║██████╔╝███████╗█████╗  ██████╔╝██║   ██║███████║██║
██║   ██║██╔══██╗╚════██║██╔══╝  ██╔══██╗╚██╗ ██╔╝██╔══██║██║
╚██████╔╝██████╔╝███████║███████╗██║  ██║ ╚████╔╝ ██║  ██║███████╗
 ╚═════╝ ╚═════╝ ╚══════╝╚══════╝╚═╝  ╚═╝  ╚═══╝  ╚═╝  ╚═╝╚══════╝

A self-hosted unified agent registry with built in analytics. Enterprise edition adds SSO (OIDC and SAML), Audit Logs, Security Events and organizational AI insights.

If you find Observal useful, please consider giving it a star. It helps others discover the project and keeps development going.

One command to install any agent into any supported IDE. The config files are generated per-IDE automatically.

Observal has two parts: a server (API + web UI + databases) you self-host, and a CLI you install on each developer machine.

One-line install (requires Docker Engine ≥ 24.0 with Compose v2):

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

This downloads a Docker Compose package, runs guided setup (domain, secrets, ports), pulls container images from GHCR, and starts the full stack (API, web UI, PostgreSQL, ClickHouse, Redis, worker, load balancer, Prometheus, Grafana).

From source (for contributors):

git clone https://github.com/BlazeUp-AI/Observal.git && cd Observal
cp .env.example .env
make up

Standalone binary (no Python required):

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

Python (3.11+):

uv tool install observal-cli
# or: pipx install observal-cli

observal auth login
observal doctor --patch

This authenticates with your server, detects your IDE, installs telemetry hooks, and starts capturing sessions automatically.

Once logged in, run /observal inside your IDE and it takes the wheel. Pull agents, submit components, browse the registry, run diagnostics:

/observal pull security-auditor
/observal scan
/observal doctor

Or just tell your agent what you want and it figures out the right commands.

An agent bundles 5 component types into a single installable package: MCP servers, skills, hooks, prompts, and sandboxes. You define them in YAML, publish to the registry, and anyone can pull them with one command. The platform generates the right config files for whichever IDE the user runs.

observal pull security-auditor --ide pi

Once connected, Observal captures your entire coding session: every user prompt, every thinking block, every assistant response, every tool call with its full input and output. No sampling, no summarization. The raw session flows into ClickHouse for querying and analysis.

Browse published agents, see which IDEs they support, check download counts and ratings, and install with one command. Admins review submissions before they go live. Version diffs show exactly what changed between releases.

Browse, search, and install agents with IDE compatibility badges:

Build agents visually with live config preview for every IDE:

Components library: MCPs, Skills, Hooks, Prompts, Sandboxes:

Full session overview with token counts, models, tools, and turn-by-turn timeline:

Every turn captured: user prompt, tool calls, thinking block, assistant response:

Drill into any span to see exact tool inputs and outputs:

Admin review queue with full prompt inspection and approve/reject:

Version diffs show exactly what changed between releases:

Leaderboard tracks top agents and components by downloads:

AI-powered insight reports analyze usage patterns across all sessions — what's working, what's hindering, and quick wins. Powered by LiteLLM, works with any provider (Anthropic, OpenAI, Bedrock, Gemini, Azure, Ollama).

See Insights LLM Setup for configuration.

Source-available under a separate license. Activated with a signed JWT key. Core never imports from ee/, the open-source edition is fully functional without it.

Enterprise adds:

• Audit trail/logs with parameterized search and CSV export
• SAML SSO and SCIM provisioning
• Executive dashboard for org-wide agent performance

Audit log with parameterized search:

The server and CLI are the same package for all editions. Enterprise features activate at runtime when a valid license key is present:

# Pass the key during server install
curl -fsSL https://raw.githubusercontent.com/BlazeUp-AI/Observal/main/install-server.sh | bash -s -- --license-key YOUR_KEY

# Or add it later to your .env
echo 'OBSERVAL_LICENSE_KEY=your.key' >> .env
make rebuild

Full docs at docs.observal.io

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.

GitHub Discussions for questions and ideas. Discord for chat. Open Issues for confirmed bugs.

observal support bundle

Produces a redacted diagnostic archive. Review before sharing: observal support inspect observal-support-*.tar.gz

For live debugging, Observal uses loguru-based dev logging (internally called "optic"). Stream logs with:

observal logs

Logs are written to ~/.observal/logs/dev.log and include structured context for every request, background job, and telemetry event.

Report vulnerabilities via GitHub Private Vulnerability Reporting or email contact@blazeup.app. Do not open a public issue. See SECURITY.md.

GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE.