> For the complete documentation index, see [llms.txt](https://docs.observal.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.observal.io/core-concepts/core-concepts.md).

# Overview

The vocabulary you need to be productive with Observal.

## The registry

The registry stores users, agents, components, review state, and alert rules in PostgreSQL. Session events and aggregates are stored separately in ClickHouse. See [Session tracking and reconciliation](/core-concepts/session-tracking.md) for the complete session data flow.

## Registry components

Six component types are available. Agents bundle the other five.

| Type           | What it is                                                                                                  |
| -------------- | ----------------------------------------------------------------------------------------------------------- |
| **Agent**      | A complete, installable AI agent. Bundles MCP servers, skills, hooks, prompts, and sandboxes into one YAML. |
| **MCP Server** | A [Model Context Protocol](https://modelcontextprotocol.io/) server, the tools an agent can call.           |
| **Skill**      | A portable instruction package agents load on demand.                                                       |
| **Hook**       | A lifecycle callback that runs on session start, tool use, session end, and other supported events.         |
| **Prompt**     | A named, parameterized prompt template with variable substitution.                                          |
| **Sandbox**    | A Docker execution environment for running code the agent generates.                                        |

Anyone can publish. Admin review controls what appears in the public listing, but your own items are usable immediately without approval.

## Canonical identity

An agent or component has a canonical `namespace/slug` identity. The namespace is the owner's username. The slug is stable within that namespace. Display names can change without changing the canonical identity.

UUIDs are the stable reconciliation key. The server supplies canonical namespace, slug, display name, qualified name, and review status. Installed versions in the local lockfile remain local pins.

## Deployment mode

SSO-only access is controlled by `deployment.sso_only`:

| Mode                                  | Self-registration | Bootstrap                                           | Auth                          |
| ------------------------------------- | ----------------- | --------------------------------------------------- | ----------------------------- |
| `deployment.sso_only=false` (default) | Yes               | Yes, a fresh server creates an admin on first login | Email and password or API key |
| `deployment.sso_only=true`            | No                | No                                                  | SSO only                      |

Most self-hosters use `deployment.sso_only=false`.

## Next

* [Session tracking and reconciliation](/core-concepts/session-tracking.md)
* [Use cases](/use-cases/use-cases.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.observal.io/core-concepts/core-concepts.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.