# Installation

Install the Observal CLI on your machine. The CLI is what you use to log in, instrument IDE configs, pull agents, and query traces.

If you also want to **self-host** the Observal server (API + web UI + databases), see [Self-Hosting](/self-hosting/docker-compose.md).

> \[!NOTE] Self-hosting requires Docker Engine ≥ 24.0 with Compose v2 (`docker compose`, not `docker-compose`). Homebrew's Docker formula is outdated. Install [Docker Desktop](https://docs.docker.com/get-docker/) or use your distro's upstream packages. Verify with `docker version` and `docker compose version`.

## Install (standalone binary)

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

**Community edition (default):**

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

**Enterprise edition** (requires a valid license key):

```bash
curl -fsSL https://raw.githubusercontent.com/BlazeUp-AI/Observal/main/install.sh | bash -s -- --license-key YOUR_KEY
```

A valid Ed25519-signed license key downloads the enterprise binary and saves the key to `~/.observal/config.json`. Without a key (or with an invalid one), the installer falls back to community edition.

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

Verify it worked:

```bash
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):**

```bash
uv tool install observal-cli
```

**pipx:**

```bash
pipx install observal-cli
```

**pip:**

```bash
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` | `asyncpg` (for the `observal migrate` command) | If you operate the server and run DB migrations from the CLI |
| `all`     | Both of the above                              | If you do both                                               |

Install an extra:

```bash
uv tool install 'observal-cli[sandbox]'
```

## Install from source (for contributors)

```bash
git clone https://github.com/BlazeUp-AI/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-shim`        | stdio shim between your IDE and stdio MCP servers    |
| `observal-proxy`       | HTTP proxy between your IDE and HTTP/SSE MCP servers |
| `observal-sandbox-run` | Sandbox runner invoked by Observal sandboxes         |

You will almost never call the shim, proxy, or sandbox runner directly. The CLI wires them into your IDE config for you.

## Upgrade

```bash
observal self upgrade
```

## Uninstall

Standalone binary:

```bash
rm "$(which observal)"
```

Python install:

```bash
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:

```bash
rm -rf ~/.observal
```

## Next

-> [Quickstart](/getting-started/quickstart.md)


---

# Agent Instructions: 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:

```
GET https://docs.observal.io/getting-started/installation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.