# Observal: a self-hosted registry for Skills, MCP servers and Agents

> Observal packages internal AI components into versioned units, serves them from a governed registry you host yourself, and generates the right config for each coding harness. The insight engine is the interesting half, and the part the documentation describes least.

**Observal/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.

- Repository: https://github.com/Observal/Observal
- Website: https://observal.io/
- Stars: 3,969 · Forks: 1,107
- Language: Python
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/observal-observal

## The duplication problem Observal is built around

Most organizations that use coding agents heavily end up with the same failure. Someone writes a Skill, an MCP server, or a subagent prompt, puts it in a repository, and moves on. Six months later a different team writes a near-identical component because they never found the first one. The README names this directly: components are stored "in siloed github repositories with little to no documentation", so users cannot locate similar work and rebuild it.

The second problem is quieter. When a Skill produces a subtly wrong answer, nothing throws an error. The README describes the consequence: AI failures "don't trigger static error codes: they hallucinate or provide subtly incorrect answers". A maintainer who cannot see how a component is used has no way to tell whether it is helping. Observal's answer is to be the system of record for these components and to collect session data alongside them.

The audience is therefore narrow and specific: platform or developer-experience teams inside an organization that has already accumulated internal AI components and wants one place to publish, approve and install them. It is not aimed at individuals sharing prompts on the open internet.

## Server, CLI and what actually flows between them

Observal ships as two pieces. The server is an API, a web UI and a set of databases that you host. The CLI is installed on each developer machine and is published to PyPI as observal-cli. The pyproject.toml declares Python 3.11 or later and pulls in typer, click, httpx, rich, pyyaml, questionary, docker, asyncpg, packaging and loguru. It also marks itself as Development Status 4 - Beta, which is worth reading literally.

The server side is not a single process. The .env.example lists three infrastructure endpoints: DATABASE_URL pointing at PostgreSQL over asyncpg, CLICKHOUSE_URL, and REDIS_URL. The repository root carries prometheus.yml and a grafana/ directory, so the deployment expects a metrics stack alongside the application databases. ClickHouse is where the analytical load lands; that is the storage decision that makes the insight engine possible, because session and usage data is append-heavy and does not fit a transactional schema well.

The CLI's job is rendering. The README states that config files are generated per-harness automatically, and the supported list covers Claude Code, Kiro, Cursor, Pi, Copilot (both CLI and VS Code extension), Codex, OpenCode, Antigravity CLI and Goose. This is the concrete mechanism behind "one command to install any agent into any supported harness": rather than documenting nine separate setup procedures, the CLI writes the file each harness expects. That is a real maintenance saving, though it also means every harness format change is a change Observal has to absorb.

The packaging model is the other half. A component bundles Skills, MCP servers, hooks, prompts and sandboxes into one versioned unit, and the registry tracks version diffs and submission approval. The README describes a governed flow: review submissions, approve internal agents, inspect version diffs.

## Deploying the server with the one-line installer

The README gives a single command for the server. It requires Docker Engine 24.0 or later with Compose v2. According to the README, the script downloads a Docker Compose package, generates operator-owned secret files with restricted container-group access, binds published ports to loopback by default, pulls images from GHCR, and starts the stack.

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

Piping a remote script into bash is a choice worth pausing on. The mitigations the README lists (loopback-bound ports, restricted secret file permissions) address the running state, not the download itself. If that matters to you, fetch install-server.sh, read it, and run it locally instead.

For manual configuration, copy the example environment file and set the values. The three infrastructure URLs are required for every deployment, and SECRET_KEY must be a random string of at least 32 characters in production.

```bash
cp .env.example .env
python3 -c "import secrets; print(secrets.token_hex(32))"
```

The generated value goes into SECRET_KEY. The .env.example notes that JWT signing keys are an EC key pair generated automatically on first start into JWT_KEY_DIR, so you do not create those by hand.

On the client side, install the CLI from PyPI. The optional migrate extra is only needed if you intend to run the server's Parquet export and import pipeline.

```bash
pip install observal-cli
pip install "observal-cli[migrate]"
```

After that, point the CLI at your server and install a component into a harness. The README does not reproduce the exact subcommand syntax in the excerpt available, so check the CLI's own help output before scripting anything.

## Where the configuration model gets awkward

The .env.example is explicit that as of v1.0 only boot-time infrastructure variables live in the file. Runtime settings, which the file enumerates as eval models, security policies, SAML and retention, are configured through the Settings page in the admin UI and are restricted to a super admin.

That is a defensible design for a product with a UI, and a poor fit for anyone who treats configuration as code. A team that manages deployments through GitOps, or that wants to review a retention-policy change in a pull request, cannot do it here. Changing SAML settings means a human clicking through an admin page, and the change is not visible in your repository history. The split between boot-time and runtime configuration is clean in principle and inconvenient in practice for infrastructure-as-code shops.

The same file carries a harder constraint: no incremental upgrade from pre-1.0 is supported, and it links to an upgrade page. If you are evaluating Observal at 1.13.1, this mostly tells you the project has already made one breaking migration and was willing to document it rather than paper over it. It also tells you that upgrading across major versions is something to plan for, not assume.

The beta classifier reinforces the point. Development Status 4 - Beta in pyproject.toml is the maintainers' own label. The last push to the repository was on 2026-09-08 and the most recent release, v1.13.1, was tagged on 2026-09-05, so the project is moving, but a beta label plus a documented breaking migration is a combination that argues for running it in a contained environment first.

## The insight engine is the differentiated part, and the least specified

Discovery layers are not novel. A private package index with a search box solves the duplication problem adequately, and many teams build one. What Observal claims beyond that is the feedback loop: adoption and session data that show which agents, tools, prompts and workflows are actually helping, plus session replay for debugging and audits.

That is the reason to pick Observal over a plain registry, and it is also where the available documentation is thinnest. The README states the capability and names the storage (ClickHouse), but the excerpt does not describe the trace format, what a session record contains, how long traces are retained by default, or what the replay interface shows. Retention is mentioned only as a runtime setting in the admin UI.

Before committing, treat the insight engine as the thing to evaluate hardest. Session traces from coding agents can contain source code, file paths, prompts and command output. The security posture of that data is a first-order question, and the README excerpt does not answer it. There is a SECURITY.md and an AI_POLICY.md in the repository root, so the project has thought about it, but you should read those files rather than assume.

If you only need discovery and versioned installation, you are paying for a ClickHouse cluster you will not use.

## How it compares to a plain internal package index

The closest alternative is not another AI registry. It is the private package index your team already runs, whether that is a private PyPI, a private npm scope, or an internal Git repository with a README convention.

The difference in approach is what gets stored and what gets generated. A package index stores an artifact and a version. Observal stores a component that spans Skills, MCP servers, hooks, prompts and sandboxes as one unit, and it knows how to write the per-harness config file for nine different coding tools. A package index has no opinion about Cursor versus Codex; you document that yourself, once per harness, and update it when a harness changes its format.

The second difference is the approval flow. A package index typically grants publish rights and trusts the publisher. Observal's registry is described as governed, with submission review and version diffs. If your organization needs a human in the loop before a component reaches other developers, that is a feature a package index does not give you.

The third difference is telemetry, and it is the one that cuts both ways. A package index tells you download counts. Observal aims to tell you whether the component worked. Download counts are cheap to collect and privacy-neutral; session traces are neither. Choose based on whether you actually need the second signal.

## Licence, upgrade cost and what to check

Observal is Apache-2.0, and the repository is thorough about it: there is a LICENSE file, a LICENSES/ directory, REUSE.toml, and SPDX headers on source files including the README itself. Apache-2.0 is permissive, includes an explicit patent grant, and imposes no copyleft obligation on your own components. There is a CLA.md and a .clabot configuration, so external contributions require signing a contributor licence agreement. That is a governance detail, not a restriction on your use of the software. For anything beyond that, talk to your own counsel.

The upgrade cost is real but bounded. The .env.example states plainly that no incremental upgrade from pre-1.0 is supported. Within the 1.x line the release cadence visible here runs from v1.12.1 on 2026-08-09 to v1.13.0 and v1.13.1 on 2026-09-05, which suggests frequent minor releases. The Makefile carries migrate and check-migrations targets, so schema migrations are a first-class part of the workflow rather than an afterthought. Budget for reading release notes before each minor bump, and for a maintenance window when the migration touches ClickHouse.

Running the server also means operating PostgreSQL, ClickHouse, Redis, Prometheus and Grafana. That is the hidden cost. The one-line installer makes the first hour easy and says nothing about the third month.

## Conclusion

Adopt Observal if your team already maintains several internal Skills or MCP servers across multiple coding harnesses and the duplication has become visible. Do not adopt it if you are a solo developer with one or two components: a self-hosted PostgreSQL, ClickHouse and Redis stack is a large amount of infrastructure for a problem you do not yet have. Before rolling it out, verify three things: that your deployment satisfies Docker Engine 24.0 or later with Compose v2, that you have read the upgrade note stating no incremental upgrade from pre-1.0 is supported, and that you are comfortable with runtime settings living in the admin UI rather than in .env.

## FAQ

### What exactly does Observal mean by an AI component?

Observal packages Skills, MCP servers, hooks, prompts and sandboxes into one versioned unit that the registry stores and the CLI installs. The README describes the goal as turning these into reusable agents rather than loose files in separate repositories.

### Which coding tools can Observal install components into?

The README lists Claude Code, Kiro, Cursor, Pi, Copilot (CLI and VS Code extension), Codex, OpenCode, Antigravity CLI and Goose. The CLI generates the correct config file for each harness instead of you maintaining separate setup instructions.

### Does Observal need Docker to run the server?

Yes. The one-line install script requires Docker Engine 24.0 or later with Compose v2, and it pulls the container images from GHCR. The server also expects PostgreSQL, ClickHouse and Redis endpoints, which the .env.example lists as required for every deployment.

### Where do runtime settings like retention and SAML live in Observal?

In the admin UI, not in .env. The .env.example states that as of v1.0 only boot-time infrastructure variables live in the environment file, and that eval models, security policies, SAML and retention are configured through the Settings page, which is restricted to a super admin.

## Sources

- [License: Apache-2.0](https://github.com/Observal/Observal/blob/main/LICENSE)
- [Observal/Observal on GitHub](https://github.com/Observal/Observal)
- [Project website](https://observal.io/)
- [README](https://github.com/Observal/Observal/blob/main/README.md)
- [Releases](https://github.com/Observal/Observal/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/observal-observal