Run a team-wide agent registry

Once two or more people are authoring agents, you need a single source of truth. Observal becomes your team’s internal Docker Hub for AI agents, with review, RBAC, and telemetry baked in.

What changes at team scale

Discovery: everyone sees the same list of agents, MCPs, skills, hooks, prompts, and sandboxes.
Review: admins approve what appears in the public listing. Authors’ own items are still immediately usable.
Governance: RBAC roles (super_admin, admin, reviewer, user) control who can publish and approve.
Visibility: centralized dashboards instead of “ask Sarah which version she’s running.”

Setup shape

Deploy once, everyone points at it. Install the server once (Self-Hosting). Then every engineer installs the CLI and runs observal auth login pointed at your shared server URL.

Users and roles

Four roles, RBAC-enforced on every endpoint.

Role	Can	Cannot
`user`	Publish components (subject to review), install agents, view their own traces	Approve submissions, see other users’ private traces, change server settings
`reviewer`	Everything `user` can + approve/reject submissions	Change server settings, manage users
`admin`	Everything `reviewer` can + manage users, change server settings	Only restriction: certain super-admin operations
`super_admin`	Everything	-

Manage users:

observal admin users --output json
observal admin reset-password <email> --generate --output json
observal admin delete-user <email> --force --output json

Change a role via the web UI (/settings/users) or the API (PUT /api/v1/admin/users/{id}/role).

Onboarding a new engineer

Two commands to get them productive:

# The new engineer runs:
curl -fsSL https://raw.githubusercontent.com/Observal/Observal/main/install.sh | bash
observal auth login --server https://observal.your-company.internal

For managed deployments, users authenticate through SSO or are provisioned by an admin. See Authentication and SSO. After logging in, they can:

observal agent list                           # see every agent the team has published
observal agent pull team-reviewer --harness claude-code # install one
observal scan                                 # discover what they have installed
observal doctor patch --all-harnesses        # instrument everything

Review workflow

Authors submit. Reviewers approve. Approved items appear in the public listing.

observal review list --output json
observal review show <number> --output json
observal review approve <number> --output json
observal review request-changes <number> --body "missing env var docs" --output json
observal review publish <number> --output json

What reviewers look for:

Does the README/description make it clear what the component does?
Does the MCP analysis (from submit) look correct: tools, env vars, transport?
Are required env vars documented?
Is the repo URL trustworthy (pinned commit or tag)?

Everything published is visible to the author immediately. Review controls what appears in the public listing.

Telemetry across the whole team

Because every engineer’s session telemetry flows into the same server, observal ops becomes a team dashboard:

observal ops top --type agent           # most-used agents across the team
observal ops top --type mcp             # hottest MCP servers

Filters in the web UI let you slice by user, agent, harness, and time range.

SSO and audit considerations

For orgs that need SSO and audit logging, configure OIDC in Admin → SSO:

Setting	Value
`oauth.client_id`	Your IdP client ID
`oauth.client_secret`	Your IdP client secret
`oauth.server_metadata_url`	Your IdP discovery URL

Restart the API after OIDC changes. See Authentication and SSO.

→ Self-Hosting: the operator’s playbook for actually running the server this use case depends on.

Getting Started

Core Concepts

Use Cases

CLI Reference

Self-Hosting

Integrations

Reference

Security

Architecture Decisions

Contributing