diff --git a/src/lib/navigation.ts b/src/lib/navigation.ts
index 059c31d7..ca09232f 100644
--- a/src/lib/navigation.ts
+++ b/src/lib/navigation.ts
@@ -60,7 +60,8 @@ export const tabNavigation: NavTab[] = [
title: 'Self-Hosting',
items: [
{ title: 'Overview', href: '/docs/self-hosting' },
- { title: 'System requirements', href: '/docs/self-hosting/requirements' },
+ { title: 'Requirements', href: '/docs/self-hosting/requirements' },
+ { title: 'Installation', href: '/docs/self-hosting/installation' },
{ title: 'Environment variables', href: '/docs/self-hosting/environment' },
{ title: 'Configuration', href: '/docs/self-hosting/configuration' },
{ title: 'Docker Compose', href: '/docs/self-hosting/docker-compose' },
diff --git a/src/pages/docs/self-hosting/requirements.mdx b/src/pages/docs/self-hosting/requirements.mdx
index 4e0ce3be..f23aa952 100644
--- a/src/pages/docs/self-hosting/requirements.mdx
+++ b/src/pages/docs/self-hosting/requirements.mdx
@@ -1,24 +1,36 @@
---
-title: "Self-Hosting Requirements"
-description: "Hardware sizing tiers, supported platforms, OS compatibility, and network port requirements before deploying Future AGI with Docker Compose."
+title: "Requirements"
+description: "System requirements and support for self-hosting Future AGI."
---
-## About
+## In this page
-Hardware tiers, supported platforms, and the network ports each service uses. Read this first to size your environment before running [Docker Compose](/docs/self-hosting/docker-compose).
+Check three things before you install:
+
+- A host that meets the sizing for your usage
+- The required software: Docker and Git
+- A supported platform
+
+Get these right and the [Installation](/docs/self-hosting/installation) run works on the first try.
+
+
+For a local trial: **4 CPU cores, 8 GB RAM, 20 GB disk**, Docker Engine 24+, Docker Compose v2.20+, and Git.
+
## Hardware tiers
+Pick the row that matches how you'll use the instance. The stack runs on the Evaluation tier, but ClickHouse and the Temporal worker are the resource drivers. Under-provisioning RAM is the most common cause of a failed first boot.
+
| Tier | Use case | CPU | RAM | Disk |
|---|---|---|---|---|
| **Evaluation** | Local trial, single user | 4 cores | 8 GB | 20 GB |
-| **Team** | 1–20 users, regular eval runs | 8 cores | 16 GB | 50 GB |
+| **Team** | 1-20 users, regular eval runs | 8 cores | 16 GB | 50 GB |
| **Production** | 20+ users, high throughput | 16+ cores | 32+ GB | 200 GB+ SSD |
-Resource drivers: ClickHouse and Temporal worker each hold ~1 GB RAM at steady state. First image build is ~6 GB disk. ClickHouse grows with trace volume; Postgres stays small.
+ClickHouse and the Temporal worker each hold ~1 GB RAM at steady state. ClickHouse grows with trace volume over time; Postgres stays small. Pulling the images takes a few GB of disk on the first run.
-Docker Desktop (Mac/Windows): Settings → Resources → set RAM ≥ 8 GB, disk ≥ 64 GB. The defaults (2–4 GB RAM) will OOM-kill ClickHouse or the backend.
+On Docker Desktop (Mac/Windows), raise the limits in **Settings → Resources**: RAM ≥ 8 GB, disk ≥ 64 GB. The defaults (2-4 GB RAM) will OOM-kill ClickHouse or the backend before the stack finishes booting.
## Software
@@ -27,70 +39,62 @@ Docker Desktop (Mac/Windows): Settings → Resources → set RAM ≥ 8 GB, disk
|---|---|---|
| Docker Engine | 24.0+ | `docker --version` |
| Docker Compose | v2.20+ | `docker compose version` |
+| Git | 2.0+ | `git --version` |
+Install the tools with Homebrew, then start Colima:
```bash
-brew install docker docker-compose colima
+brew install docker docker-compose colima git
colima start --cpu 4 --memory 8 --disk 64
```
-Or install [Docker Desktop for Mac](https://docs.docker.com/desktop/setup/install/mac-install/) and allocate ≥ 8 GB RAM in Settings → Resources.
+Install the tools with apt, then enable the Docker daemon:
```bash
-sudo apt-get install -y docker.io docker-compose-v2
+sudo apt-get install -y docker.io docker-compose-v2 git
sudo systemctl enable --now docker
sudo usermod -aG docker $USER # log out and back in
```
-Install [Docker Desktop for Windows](https://docs.docker.com/desktop/setup/install/windows-install/) with WSL 2 backend. Allocate ≥ 8 GB RAM in Settings → Resources.
+Install [Docker Desktop for Windows](https://docs.docker.com/desktop/setup/install/windows-install/) with the WSL 2 backend, then set the memory limit in WSL, not Docker's UI: add `memory=8GB` under a `[wsl2]` section in `%UserProfile%\.wslconfig` and run `wsl --shutdown` to apply. The **Settings → Resources** sliders apply only to the Hyper-V backend.
## Platform compatibility
-The `code-executor` service requires `privileged: true`. Platforms that block it will crash the service; the rest of the stack still runs.
+Future AGI runs on any host that allows **privileged containers**. The `code-executor` service needs `privileged: true` to sandbox the user code it runs for evaluations, so platforms that block privileged mode lose that one service: the rest of the stack still runs, but code-based eval features are unavailable.
| Platform | Supported | Notes |
|---|---|---|
| Linux bare metal / EC2 / GCE / Azure VM | Yes | Full support |
-| GKE / EKS with privileged enabled | Yes | Requires PodSecurityPolicy exception |
+| GKE / EKS with privileged enabled | Yes | Requires a PodSecurityPolicy exception |
| ECS Fargate | No | `privileged: true` not supported |
| Google Cloud Run | No | Same |
| Render / Railway / Fly.io | No | Managed platforms block privileged mode |
-## Ports reference
+Helm/Kubernetes and air-gapped install are on the roadmap. Docker Compose is the supported path today.
-All ports are configurable via `.env`.
+## Network ports
-| Service | Default | Exposed to | `.env` key |
+Make sure these host ports are free before you install, or remap any that collide. Every published port reads from `.env` with a built-in default (for example `${FRONTEND_PORT:-3000}`), so you can change one without touching the Compose file.
+
+| Service | Default | Bind | `.env` key |
|---|---|---|---|
| Frontend | `3000` | `0.0.0.0` | `FRONTEND_PORT` |
| Backend API | `8000` | `0.0.0.0` | `BACKEND_PORT` |
-| Gateway | `8090` | Internal only | `GATEWAY_PORT` |
-| Model serving | `8080` | Internal only | `SERVING_PORT` |
-| Code executor | `8060` | Internal only | `CODE_EXECUTOR_PORT` |
-| Postgres | `5432` | `127.0.0.1` (dev: public) | `PG_PORT` |
-| ClickHouse HTTP | `8123` | `127.0.0.1` (dev: public) | `CH_HTTP_PORT` |
-| ClickHouse TCP | `9000` | `127.0.0.1` (dev: public) | `CH_PORT` |
-| Redis | `6379` | `127.0.0.1` (dev: public) | `REDIS_PORT` |
+| Gateway | `8090` | `0.0.0.0` | `AGENTCC_GATEWAY_PORT` |
+| Model serving | `8080` | `0.0.0.0` | `SERVING_PORT` |
+| Code executor | `8060` | `0.0.0.0` | `CODE_EXECUTOR_PORT` |
+| Postgres | `5432` | `127.0.0.1` | `PG_PORT` |
+| ClickHouse HTTP | `8123` | `127.0.0.1` | `CH_HTTP_PORT` |
+| ClickHouse TCP | `9000` | `127.0.0.1` | `CH_PORT` |
+| Redis | `6379` | `127.0.0.1` | `REDIS_PORT` |
| MinIO API | `9005` | `127.0.0.1` | `MINIO_API_PORT` |
| MinIO console | `9006` | `127.0.0.1` | `MINIO_CONSOLE_PORT` |
-| Temporal | `7233` | `127.0.0.1` (dev: public) | `TEMPORAL_PORT` |
-| Temporal UI | `8085` | Dev mode only | `TEMPORAL_UI_PORT` |
+| Temporal | `7233` | `127.0.0.1` | `TEMPORAL_PORT` |
| PeerDB server | `9900` | `127.0.0.1` | `PEERDB_PORT` |
| PeerDB UI | `3001` | `0.0.0.0` | `PEERDB_UI_PORT` |
-In production, only the frontend and backend ports should be internet-facing, and only behind a TLS-terminating reverse proxy.
-
-## Next Steps
-
-
-
- Clone, configure, and run the full stack.
-
-
- Set secrets and tune runtime flags before first boot.
-
-
+The data stores (Postgres, ClickHouse, Redis, MinIO, Temporal) bind to `127.0.0.1`; the application services bind to `0.0.0.0`. PeerDB server and UI only run when you enable the CDC stack with `COMPOSE_PROFILES=full`, so those two ports are only in use in that mode.