Requirements
August 8, 2026 · View on GitHub
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 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, orpip
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-netbridge 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.1by 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:
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 for trust boundaries and residual network risks.