GitHub - Observal/Observal: Observal is a local registry and analytics platform for your AI components. Setup Observal, define the scope and share your Skills, MCPs and Agents.

Why teams use Observal

Package components into reusable agents: Bundle Skills, MCP servers, hooks, prompts, and sandboxes into one versioned unit. Run a governed registry: Review submissions, approve internal agents, inspect version diffs, and give developers one trusted place to install from. Render across multiple Coding IDE/CLI: Generate the correct config for each supported harness instead of maintaining separate setup instructions for every harness. Learn what works: Use real adoption and session data to find which agents, tools, prompts, and workflows are helping teams. Replay sessions when needed: Use traces as evidence for debugging, review, audits, and deeper analysis.

Supported harnesses

harness

Claude Code

Kiro

Cursor

Pi

Copilot (CLI & VS Code Extension)

Codex

OpenCode

Antigravity CLI

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

Quick Start Observal has two parts: a server (API + web UI + databases) you self-host, and a CLI you install on each developer machine. 1. Deploy the server One-line install (requires Docker Engine ≥ 24.0 with Compose v2): curl -fsSL https://raw.githubusercontent.com/Observal/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). Deployment docs are linked directly from this README:

Setup guide: fastest path from zero to a working stack Self-hosting overview: deployment models and operator docs Production deployment: hardened production topology Databases: Postgres, ClickHouse, migrations, retention Upgrades: safe upgrade and rollback flow Backup and restore: backup plan before upgrades

From source (for contributors): git clone https://github.com/Observal/Observal.git && cd Observal cp .env.example .env make up 2. Install the CLI Standalone binary (no Python required): curl -fsSL https://raw.githubusercontent.com/Observal/Observal/main/install.sh | bash Python (3.11+): uv tool install observal-cli # or: pipx install observal-cli 3.

Connect your harness observal auth login observal doctor --patch This authenticates with your server, detects your harness, installs telemetry hooks, starts capturing sessions automatically, and prepares it for agent installs and registry commands. Once logged in, run /observal inside your harness 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.

How Observal works Agents are portable context packages An agent bundles 5 component types into a single installable package: MCP servers, skills, hooks, prompts, and sandboxes. You define the agent once, publish it to the registry, and Observal generates the right config files for whichever supported harness or harness the user runs. observal pull security-auditor --harness pi The registry is the distribution layer Browse published agents, see which harnesses 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, so teams can safely evolve shared context. Insights show what is helping Observal turns real usage into reports about which agents, prompts, tools, and workflows are working or getting in the way. Use those insights to improve shared context instead of guessing from anecdotes. Session traces provide the evidence When you need to debug, audit, or understand a result, Observal can replay the full coding session: user prompts, thinking blocks, assistant responses, and tool calls with their inputs and outputs. The traces support registry and insight workflows rather than defining the product.

Agent Registry Browse, search, and install agents with harness compatibility badges:

Build agents visually with live config preview for every harness:

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

Agent Insights 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.

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

Review and Governance 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:

Open-source features Audit logs, SAML SSO, SCIM provisioning, and the executive dashboard are included in the Apache-2.0 distribution. Audit log with parameterized search:

Documentation Full docs at docs.observal.io. Start here for deployment and operations:

Need Link

Fast local or source setup SETUP.md

Self-hosting overview docs/self-hosting/README.md

Production deployment docs/self-hosting/production-deploy.md

Single-node deployment docs/self-hosting/single-node-deploy.md

Docker Compose setup docs/self-hosting/docker-compose.md

Databases and migrations docs/self-hosting/databases.md

Upgrades docs/self-hosting/upgrades.md

Backup and restore docs/self-hosting/backup-and-restore.md

Tech Stack

Layer Technology

Frontend Vite 6, React 19, TanStack Router, Tailwind CSS 4, shadcn/ui

Backend Python 3.11+, FastAPI, Strawberry GraphQL

Databases PostgreSQL 16 (registry), ClickHouse (telemetry)

Queue Redis + arq

CLI Python, Typer, Rich

Telemetry Session hooks, local transcript reconciliation, push-based ingest

Deployment Docker Compose (10 services), Kubernetes (Helm)

Contributing See CONTRIBUTING.md. The short version:

Fork and clone make hooks to install pre-commit hooks Create a feature branch Run make lint and make test Open a PR

See AGENTS.md for internal codebase context. Community GitHub Discussions for questions and ideas. Discord for chat. Open Issues for confirmed bugs. Reporting Issues observal support bundle Produces a redacted diagnostic archive.