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. macOS / Linux:

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

Windows (PowerShell):

irm https://raw.githubusercontent.com/Observal/Observal/main/install.ps1 | iex

This downloads the latest release binary for your platform and places it on your PATH. On Windows it installs to %LOCALAPPDATA%\Programs\Observal and updates your user PATH (open a new terminal afterwards). Set OBSERVAL_VERSION or OBSERVAL_BIN_DIR before running to pin a version or change the install directory. Connecting to a server your team already runs? See the Setup guide. 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

The Python package includes the Docker SDK. The migrate extra adds pyarrow for observal server migrate:

uv tool install 'observal-cli[migrate]'

Install from source (for contributors)

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

What gets installed

The Python package provides three entry points:

Command	Purpose
`observal`	The main CLI
`observal-sandbox-run`	Sandbox runner invoked by Observal sandboxes
`observal-sandbox-mcp`	MCP adapter used by sandbox execution

You will almost never call the sandbox helpers directly. The CLI wires them 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

-> Quickstart

Getting Started

Core Concepts

Use Cases

CLI Reference

Self-Hosting

Integrations

Reference

Security

Architecture Decisions

Contributing