Observal
Observal is self-hosted registry for your coding agent extensions with a built in insight engine. Setup Observal, define the scope and share your Skills, MCPs and Agents with your peers.
Install / Use
npx skills add Observal/ObservalInstalls into whichever agent you are using.
.cursorrules
Cursor IDE rules (legacy)
Quality Score
Category
Data & AnalyticsSupported Platforms
Tags
Skill content
View source on GitHubObserval is the control plane and system of record for internal AI components
<p> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square" alt="License"></a> <img src="https://img.shields.io/badge/python-3.11+-3776ab?style=flat-square&logo=python&logoColor=white" alt="Python"> <a href="https://pypi.org/project/observal-cli/"><img src="https://img.shields.io/pypi/v/observal-cli?style=flat-square&logo=pypi&logoColor=white&label=pypi" alt="PyPI version"></a> <a href="https://github.com/Observal/Observal/graphs/contributors"><img src="https://img.shields.io/github/contributors/Observal/Observal?style=flat-square&logo=github" alt="Contributors"></a> <a href="https://discord.gg/SFPjnTWddk"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fdiscord.com%2Fapi%2Fv10%2Finvites%2FSFPjnTWddk%3Fwith_counts%3Dtrue&query=%24.approximate_member_count&label=Discord&logo=discord&color=5865F2&style=flat-square" alt="Discord Server"></a> <a href="https://github.com/orgs/Observal/packages?repo_name=Observal"><img src="https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Haz3-jolt/b28aba6d0efebb0b430d43c8068feb91/raw/ghcr-pulls.json&style=flat-square" alt="GHCR pulls"></a> <a href="https://artifacthub.io/packages/search?repo=observal"><img src="https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/observal" alt="Artifact Hub"></a> <a href="https://cla-assistant.io/Observal/Observal"><img src="https://cla-assistant.io/readme/badge/Observal/Observal" alt="CLA assistant" /></a> <a href="https://scorecard.dev/viewer/?uri=github.com/Observal/Observal"><img src="https://api.scorecard.dev/projects/github.com/Observal/Observal/badge" alt="OpenSSF Scorecard"></a> <a href="https://www.bestpractices.dev/projects/13472"><img src="https://www.bestpractices.dev/projects/13472/badge" alt="OpenSSF Best Practices"></a> <a href="https://codecov.io/gh/Observal/Observal"><img src="https://codecov.io/gh/Observal/Observal/graph/badge.svg?branch=main" alt="Codecov"></a> </p>If you find Observal useful, please consider giving it a star. It helps others discover the project and keeps development going.
What is Observal and what does it solve?
Observal is the control plane and system of record for internal AI components. Every tech-forward organization today creates internal Skills, Agents, MCP servers and other AI components to boost productivity. Though the creation of these components has been prolific, the adoption and usage of such components is sparse. Developer/AI users today end up creating their own version of AI components without reusing existing packages.
The cause is largely due to two problems:
-
Lack of a discoverability layer
Organizations store their AI components and agents in siloed github repositories with little to no documentation. Users are not able to locate similar components and this results in multiple developers creating the same/similar components again.
-
Missing feedback loop
Any software where usage patterns are not understood and the principle of user-centric development is violated tends to fade out. Such is the problem with development of MCPs, Skills and Agents. Developers publish and maintain these components with little visibility into how they're actually used. Additionally, AI failures don't trigger static error codes: they hallucinate or provide subtly incorrect answers. This leaves users clueless about what went wrong compounding the feedback problem.
Observal solves this by providing a centralized discovery layer for AI components alongside useful insights into AI usage patterns. It turns silent failures into actionable feedback, ensuring internal AI tools are continuously optimized for the people using them.
Observal supports Claude Code, Cursor, Kiro, Pi, Copilot, Codex, OpenCode, and other tools.
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 | | Goose |
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, generates operator-owned secret files with restricted container-group access, binds published ports to loopback by default, pulls container images from GHCR, and starts the stack. With a terminal it runs guided setup; without a terminal the same command applies safe defaults automatically.
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
- Release verification: verify checksums, provenance, and signed tags
- 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 the user runs.
observal pull security-auditor --harness pi
The registry is the distribution layer
The registry is where agents live. Admins review submissions, version diffs keep changes auditable, and one command installs an agent into any supported harness.
Insights close the loop
Real usage data flows back as reports: what's helping, what's getting in the way, and where to improve. Session traces provide the underlying evidence for debugging and auditing.
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:
Side-by-side version diffs before approving a new release:
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](docs/self-hosting/READ
Truncated for display — read the full file on GitHub.
Related Skills
Agent-Reach
84.2kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
headroom
73.4kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
ruflo
73.0k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
CowAgent
47.1kOpen-source super AI assistant & Agent Harness. Plans tasks, runs tools and skills, self-evolves with memory and knowledge. Multi-agent, multi-model, multi-channel. Lightweight, extensible, one-line install.
