Installation

Observal has two parts: a server you self-host and a CLI installed on each developer machine.

Install the server

The server runs as a Docker Compose stack (API, web UI, PostgreSQL, ClickHouse, Redis, worker, load balancer). Prometheus and Grafana are optional deployment overlays.

[!NOTE] Requires Docker Engine ≥ 24.0 with Compose v2 (docker compose, not docker-compose). Homebrew's Docker formula is outdated. Install Docker Desktop or use your distro's upstream packages. Verify with docker version and docker compose version.

One-line install:

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

This downloads a config package, runs guided setup (domain, secrets, ports), pulls container images from GHCR, and starts the full stack.

From source (for contributors):

git clone https://github.com/Observal/Observal.git && cd Observal
cp .env.example .env
make up

For deployment options, see Self-Hosting and Production deployment.

Install the CLI

The CLI is what you use to log in, instrument harness configs, pull agents, and query traces.

Install (standalone binary)

The standalone binary is the simplest way to install. No Python required.

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

This downloads the latest release binary for your platform and places it on your PATH.

This validates the Ed25519-signed key, installs the CLI, and writes the key to ~/.observal/config.json. If the key is invalid or expired, the installer exits with an error.

Verify it worked:

observal --version

Alternative: install with Python

If you prefer to install via Python, use one of these methods. Requires Python 3.11 or newer.

uv (recommended):

uv tool install observal-cli

pipx:

pipx install observal-cli

pip:

pip install --user observal-cli

Optional extras

Observal ships with two opt-in extras for the Python install:

Extra	What it adds	When to install
sandbox	Docker SDK (for sandbox execution)	If you run agents inside Observal sandboxes
migrate	pyarrow (for observal server migrate)	If you move registry and telemetry data between deployments
all	Both of the above	If you do both

Install an extra:

uv tool install 'observal-cli[sandbox]'

Install from source (for contributors)

git clone https://github.com/Observal/Observal.git
cd Observal
uv tool install --editable .

What gets installed

Four entry points land on your PATH:

Command	Purpose
observal	The main CLI
observal-sandbox-run	Sandbox runner invoked by Observal sandboxes

You will almost never call the sandbox runner directly. The CLI wires it into your harness config for you.

Upgrade

observal self upgrade

Uninstall

Standalone binary:

rm "$(which observal)"

Python install:

uv tool uninstall observal-cli
# or: pipx uninstall observal-cli
# or: pip uninstall observal-cli

Uninstalling the CLI does not remove your config (~/.observal/). Delete that folder if you want a clean slate:

rm -rf ~/.observal

Next

-> Quickstart