> 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/self-hosting/requirements.md).

# Requirements

Minimum and recommended specs for running the Observal stack.

## Hardware

| Profile          | CPU     | Memory | Disk              | Who it's for                                             |
| ---------------- | ------- | ------ | ----------------- | -------------------------------------------------------- |
| Developer        | 2 vCPU  | 4 GB   | 20 GB             | One engineer, local machine                              |
| Small team (≤10) | 2 vCPU  | 6 GB   | 50 GB             | Small deployment, moderate telemetry                     |
| Team (10–50)     | 4 vCPU  | 12 GB  | 200 GB + fast SSD | Typical production deployment                            |
| Large team (50+) | 8+ vCPU | 32 GB  | 500 GB + fast SSD | High telemetry volume; consider externalizing ClickHouse |

The stack's Docker memory limits out-of-the-box:

| Service               | Limit  |
| --------------------- | ------ |
| `observal-api`        | 512 MB |
| `observal-worker`     | 512 MB |
| `observal-web`        | 256 MB |
| `observal-clickhouse` | 1 GB   |
| `observal-redis`      | 256 MB |
| `observal-grafana`    | 512 MB |

ClickHouse is the memory-hungry one. On a long-running team server, bump it to 2–4 GB in `docker/docker-compose.yml`.

## Disk: where the data goes

The heaviest user of disk is **ClickHouse**. Growth depends on:

* Number and length of harness sessions
* Raw transcript record size
* `DATA_RETENTION_DAYS`

Session transcripts vary significantly by harness and tool output size. Measure representative workloads and plan 2 to 3 times headroom over observed growth.

Postgres stays under 500 MB for most deployments; it holds only registry metadata and user accounts.

## Software

| Software           | Version    | Notes                                                    |
| ------------------ | ---------- | -------------------------------------------------------- |
| Docker             | ≥ 24.0     | With Compose v2 (`docker compose`, not `docker-compose`) |
| Linux / macOS host | any modern | Windows via WSL2 works                                   |
| Bash / zsh         | any        | For the CLI install                                      |

> \[!NOTE] Homebrew's Docker formula is outdated and may ship an older Compose version. Install [Docker Desktop](https://docs.docker.com/get-docker/) or use your distro's upstream packages to get Docker Engine ≥ 24.0 with Compose v2.

For the **CLI** (developer machines, not the server):

* **Standalone binary** (recommended) -- no dependencies, just `curl | bash`
* Or Python **3.11, 3.12, or 3.13** with `uv`, `pipx`, or `pip`

## Network

* **Outbound HTTPS**: required for image downloads and enabled integrations such as OAuth, webhooks, external Git repositories, or model providers.
* **Inbound**: the server package routes the UI, API, and session telemetry through nginx on port `8000`.
* **Between services**: the private `observal-net` bridge handles application traffic.
* **Host bindings**: new server-package installs bind nginx, the direct web port, PostgreSQL, ClickHouse, Redis, Prometheus, and Grafana to `127.0.0.1` by default.
* **Secret access**: server-package setup records the operator's group as `OBSERVAL_SECRET_GID`; only that group is added to containers that need their service-specific files.

## TLS / HTTPS

Local loopback access can use HTTP. For every remote deployment, terminate TLS 1.2 or later with Caddy, nginx, an enterprise load balancer, or a cloud ingress. Point the proxy at the loopback nginx listener on `localhost:8000`.

Example Caddy configuration:

```caddyfile
observal.your-company.internal {
  reverse_proxy localhost:8000
}
```

Set `OBSERVAL_BIND_ADDRESS` to a non-loopback address only when an external TLS proxy cannot reach loopback, or when plaintext access is an intentional private-network risk. Existing server-package installations retain their previous bind address during setup upgrades.

See the [security assurance case](/security/assurance-case.md) for trust boundaries and residual network risks.

## Next

→ [Docker Compose setup](/self-hosting/docker-compose.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/self-hosting/requirements.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.