Skip to content

docs: restructure self-hosting into modular sub-pages with architectu… #615

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Tanmaycode1 wants to merge 3 commits into
base: dev
Choose a base branch
from
Open

docs: restructure self-hosting into modular sub-pages with architectu… #615

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
31340a8
docs: restructure self-hosting into modular sub-pages with architectu…
Tanmaycode1 Apr 27, 2026
2fec5ba
Align self-hosting pages with docs style guide
hadarishav Apr 29, 2026
818ca79
fix: address PR #615 review — correct frontend port to 3000, add base…
Tanmaycode1 Apr 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 14 additions & 1 deletion src/lib/navigation.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,20 @@ export const tabNavigation: NavTab[] = [
icon: 'rocket',
items: [
{ title: 'Introduction', href: '/docs' },
{ title: 'Self-Hosting', href: '/docs/self-hosting', badge: 'New' },
{
title: 'Self-Hosting',
badge: 'New',
items: [
{ title: 'Overview', href: '/docs/self-hosting' },
Copy link
Copy Markdown
Contributor

@khushalsonawat khushalsonawat Apr 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where will this point to? There is no such file as self-hosting. Test the navigation once

{ title: 'Requirements', href: '/docs/self-hosting/requirements' },
{ title: 'Docker Compose', href: '/docs/self-hosting/docker-compose' },
{ title: 'Environment Variables', href: '/docs/self-hosting/environment' },
{ title: 'System Configuration', href: '/docs/self-hosting/configuration' },
{ title: 'User Management', href: '/docs/self-hosting/user-management' },
{ title: 'Production', href: '/docs/self-hosting/production' },
{ title: 'Troubleshooting', href: '/docs/self-hosting/troubleshooting' },
]
},
{
title: 'Quickstart',
icon: 'rocket',
Expand Down
242 changes: 65 additions & 177 deletions src/pages/docs/self-hosting.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,214 +1,102 @@
---
title: "Self-Hosting"
description: "Deploy the full Future AGI platform on your own infrastructure with Docker Compose."
description: "Run the complete Future AGI platform on your own infrastructure."
---

## About

Future AGI is the complete platform to test, guard, and monitor AI agents. Build self-improving agents that ship smarter with every version. Self-hosting runs the entire platform on your infrastructure. The backend is built on Django, the frontend on React + Vite. All data stays on your machines.
Future AGI is fully open-source. Self-hosting runs the entire stack on your machines — all traces, datasets, evaluations, and model calls stay within your network. Backend is Django, frontend is React + Vite, LLM gateway is Go.

## When to self-host
Not sure if you need this? The hosted version at [app.futureagi.com](https://app.futureagi.com) is easier to operate. Self-host when you need **data residency**, **air-gapped environments**, **cost control at scale**, or **deep customization**.

- **Data residency or compliance**: Traces, datasets, and evaluation outputs never leave your network.
- **Air-gapped environments**: Run without outbound internet access (air-gapped support is coming; Docker Compose today assumes outbound access for pulling base images and LLM APIs).
- **Cost control at scale**: For high-volume workloads, run your own infrastructure instead of the hosted plan.
- **Customization**: Modify any part of the platform to fit internal systems.

If none of these apply, the hosted version at [app.futureagi.com](https://app.futureagi.com) is easier to operate.

### Deployment options

| Option | Status |
|---|---|
| Docker Compose | Available |
| Helm Charts (Kubernetes) | Coming soon |
| Air-gapped | Coming soon |

## Prerequisites

| Requirement | Minimum | Recommended |
|---|---|---|
| RAM | 8 GB | 16 GB |
| Disk | 20 GB free | 50 GB+ |
| CPU | 4 cores | 8 cores |
| Docker | 24.0+ | Latest stable |
| Docker Compose | v2.20+ | Latest stable |
| Python | 3.11 | 3.11 |

## Install Docker and Compose

<Tabs>
<Tab title="macOS">

Install [Docker Desktop for Mac](https://docs.docker.com/desktop/setup/install/mac-install/), or use [Colima](https://github.com/abiosoft/colima) for a lighter alternative:
## Quick start

```bash
brew install docker docker-compose colima
colima start --cpu 4 --memory 8 --disk 64
```

If using Docker Desktop, go to Settings > Resources and set RAM to at least **8 GB** and disk to **64 GB**.

</Tab>
<Tab title="Linux">

```bash
sudo apt-get update
sudo apt-get install -y docker.io docker-compose-v2
sudo systemctl start docker && sudo systemctl enable docker
sudo usermod -aG docker $USER
```

Log out and back in for the group change to take effect.

</Tab>
<Tab title="Windows">

Install [Docker Desktop for Windows](https://docs.docker.com/desktop/setup/install/windows-install/) with WSL 2 backend enabled.

</Tab>
</Tabs>

Verify:

```bash
docker --version # 24.0+
docker compose version # v2.20+
```

## Clone the repository

1. [Fork the repository](https://github.com/future-agi/future-agi/fork) on GitHub.
2. Clone your fork:

```bash
git clone https://github.com/YOUR_USERNAME/future-agi.git
git clone https://github.com/future-agi/future-agi.git
cd future-agi
cp .env.example .env
```

## Configure environment

Replace every `CHANGEME` value in `.env`:

```bash
openssl rand -hex 32 # for SECRET_KEY and AGENTCC_INTERNAL_API_KEY
openssl rand -base64 24 # for PG_PASSWORD
```

| Variable | What it's for |
|---|---|
| `SECRET_KEY` | Django session signing and CSRF |
| `PG_PASSWORD` | PostgreSQL password |
| `AGENTCC_INTERNAL_API_KEY` | Shared secret between backend and gateway |

<Tip>
For a quick local test, the stack boots fine without changing anything. The `CHANGEME` values only matter when you expose the instance to others.
</Tip>

## Run the Stack

```bash
docker pull futureagi/future-agi:v1.8.19_base
docker compose up
```

To run in the background:

```bash
docker compose up -d
docker compose logs -f backend # watch startup progress
```

Once all services are up, open the frontend and backend:
First boot builds from source (~10–15 min). After `Application startup complete`:

- **Frontend**: [http://localhost:3031](http://localhost:3031)
- **Backend API**: [http://localhost:8000](http://localhost:8000)

Verify all services are healthy:

```bash
docker compose ps
```

## Create your account

The email registration flow requires Mailgun credentials (`MAILGUN_API_KEY` and `MAILGUN_SENDER_DOMAIN` in `.env`). Without Mailgun, create a user via the Django shell:

```bash
docker compose exec backend python manage.py shell -c "
from django.contrib.auth.hashers import make_password
from accounts.models import User
User.objects.create(email='you@example.com', password=make_password('your-password'))
"
```
| Service | URL |
|---|---|
| Frontend | http://localhost:3000 |
| Backend API | http://localhost:8000 |
| PeerDB UI | http://localhost:3001 — `peerdb` / `peerdb` |

Log in with those credentials.
## Deployment options

## Stop, reset, and upgrade
| Option | Status |
|---|---|
| Docker Compose | Available |
| Helm / Kubernetes | Coming soon |
| Air-gapped | Coming soon |

```bash
# Stop (data persists in Docker volumes)
docker compose down
## Architecture

# Stop and wipe all data (fresh start)
docker compose down -v
21 containers across four layers.

# Upgrade to latest
git pull
docker compose build
docker compose up -d
```

<Note>
Migrations run automatically on boot. If a migration fails after an upgrade, run `docker compose exec backend python manage.py migrate` manually and check the release notes.
</Note>

## Development mode

Use the dev overlay for hot reload and per-queue workers:

```bash
docker compose -f docker-compose.yml -f docker-compose.dev.yml up
Browser
└─ frontend (React/nginx)
└─ backend (Django) ──── gateway (Go) ──── OpenAI · Anthropic · Gemini · Bedrock
├── postgres primary DB + WAL replication
├── clickhouse analytics store
├── redis cache / pub-sub
├── minio object storage
└── temporal ──── worker background jobs / eval pipelines

postgres ──── PeerDB CDC ──── clickhouse (continuous replication)
```

This adds hot reload for backend code, per-queue Temporal workers, exposed database ports, and a Temporal UI.

## Production checklist
**Application** — `frontend` · `backend` · `worker` · `gateway` · `serving` · `code-executor`

Before exposing to users:
**Data** — `postgres` · `clickhouse` · `redis` · `minio`

- [ ] Replace every `CHANGEME` value in `.env`
- [ ] Set `ENV_TYPE=prod` and `FAST_STARTUP=false`
- [ ] Put a reverse proxy (Caddy, Nginx, or Traefik) in front for TLS
- [ ] Replace Compose databases with managed equivalents (RDS, ClickHouse Cloud, ElastiCache, S3)
- [ ] Increase backend workers (`GRANIAN_WORKERS` in `.env`) to match your CPU count
- [ ] Set up backups for PostgreSQL (`pg_dump`) and ClickHouse (`BACKUP`)
- [ ] Use a secrets manager instead of a plain `.env` file
**Workflow** — `temporal`

## Troubleshooting

| Problem | Fix |
|---|---|
| First build takes 10+ minutes | Normal. Images build from source. Subsequent starts are under 30 seconds. |
| Container keeps restarting | Run `docker compose logs SERVICE_NAME`. Usually a missing env var or port conflict. All ports are configurable in `.env`. |
| Backend never shows startup complete | Allocate at least 8 GB RAM to Docker. Check with `docker info`. |
| Frontend shows blank page | The `VITE_HOST_API` variable in `.env` must match the backend URL accessible from your browser. Changing it requires rebuilding: `docker compose build frontend`. |
**CDC (PeerDB)** — `peerdb-catalog` · `peerdb-temporal` · `peerdb-minio` · `peerdb-flow-api` · `peerdb-flow-worker` · `peerdb-flow-snapshot-worker` · `peerdb-server` · `peerdb-ui` · `peerdb-temporal-init` · `peerdb-init`

For anything not listed, open an issue at [github.com/future-agi/future-agi/issues](https://github.com/future-agi/future-agi/issues) with the output of `docker compose logs`.
| Layer | Service | Purpose |
|---|---|---|
| App | `frontend` | React SPA served by nginx |
| App | `backend` | Django REST + gRPC + WebSocket API |
| App | `worker` | Temporal worker — evals, agent loops, data jobs |
| App | `gateway` | Go LLM proxy — routing, retries, rate limits, logging |
| App | `serving` | Embeddings and small model inference |
| App | `code-executor` | nsjail-sandboxed eval code runner (`privileged: true` required) |
| Data | `postgres` | Primary DB — users, traces, datasets, evals, prompts |
| Data | `clickhouse` | Analytics DB — replicated from Postgres via PeerDB |
| Data | `redis` | Cache, rate limits, WebSocket pub/sub |
| Data | `minio` | S3-compatible object storage (swap for S3 in prod) |
| Workflow | `temporal` | Durable workflow engine — shares main Postgres |
| CDC | PeerDB stack | Continuous Postgres → ClickHouse replication (10 services) |

## Next Steps

<CardGroup cols={2}>
<Card title="Instrument Your First Agent" icon="eye" href="/docs/observe">
Set up traceAI to observe your AI application.
<Card title="Requirements" icon="server" href="/docs/self-hosting/requirements">
Hardware tiers, platform compatibility, ports reference.
</Card>
<Card title="Docker Compose" icon="docker" href="/docs/self-hosting/docker-compose">
Setup, deployment modes, day-to-day operations.
</Card>
<Card title="Environment Variables" icon="settings" href="/docs/self-hosting/environment">
Full `.env` reference — secrets, ports, flags, keys.
</Card>
<Card title="System Configuration" icon="sliders" href="/docs/self-hosting/configuration">
LLM gateway providers, PeerDB mirrors, Temporal workers.
</Card>
<Card title="Run Your First Evaluation" icon="chart-mixed" href="/docs/evaluation">
Evaluate your AI agent outputs.
<Card title="User Management" icon="user" href="/docs/self-hosting/user-management">
Create accounts via email or Django shell.
</Card>
<Card title="Set Up the LLM Gateway" icon="server" href="/docs/command-center">
Route, cache, and guard LLM requests with Agent Command Center.
<Card title="Production" icon="shield" href="/docs/self-hosting/production">
Hardening, backups, monitoring, upgrades.
</Card>
<Card title="Contributing Guide" icon="code" href="https://github.com/future-agi/future-agi/blob/main/CONTRIBUTING.md">
Set up the development environment and contribute.
<Card title="Troubleshooting" icon="wrench" href="/docs/self-hosting/troubleshooting">
Solutions for every known error.
</Card>
</CardGroup>
Loading