Docker Compose

About

Docker Compose is the supported way to run a self-hosted Future AGI instance. This page covers the full-stack deployment (all 21 services), the dev overlay with hot reload and per-queue workers, and a frontend-only mode for pointing the UI at a remote backend.

Setup

git clone https://github.com/future-agi/future-agi.git
cd future-agi
cp .env.example .env
docker pull futureagi/future-agi:v1.8.19_base
docker compose up

First boot builds from source (~10–15 min). When the backend logs Application startup complete:

• Frontend — http://localhost:3000
• Backend API — http://localhost:8000
• PeerDB UI — http://localhost:3001 · peerdb / peerdb

Replace CHANGEME secrets in .env before sharing the instance with others. See Environment Variables.

---

Deployment modes

Mode 1 — Full stack (default)

docker compose up -d          # detached
docker compose ps             # check health
docker compose logs -f backend

Starts all 21 services. Frontend binds on 0.0.0.0:3000; all data stores bind on 127.0.0.1. For production, put a reverse proxy (Caddy, nginx, Traefik) in front for HTTPS.

Mode 2 — Dev overlay

docker compose -f docker-compose.yml -f docker-compose.dev.yml up

What changes	Detail
Hot reload	./futureagi volume-mounted into backend and workers — Python changes reload without rebuild. Frontend also supports hot-reload in dev mode.
Per-queue workers	6 workers (worker-default, worker-tasks-s, worker-tasks-l, worker-tasks-xl, worker-trace-ingestion, worker-agent-compass) instead of one all-queue worker
Public DB ports	Postgres, ClickHouse, Redis, MinIO, Temporal all bind on 0.0.0.0 for host tool access
Temporal UI	http://localhost:8085
FAST_STARTUP=true	Migrations skipped on restart — run manually: docker compose exec -it backend bash -c "python manage.py migrate"

The base worker service is disabled in dev mode (moved to the oss-only profile) to prevent duplicate queue polling.

Mode 3 — Frontend only

For pointing the UI at a remote backend (another Compose project, a VM, or Future AGI Cloud).

VITE_HOST_API=https://api.your-backend.example.com \
  docker compose -f docker-compose.frontend.yml up --build

---

Operations

# Logs
docker compose logs -f backend worker

# Shell into a container
docker compose exec backend bash
docker compose exec postgres psql -U futureagi -d futureagi

# Stop (data persists)
docker compose down

# Wipe all data and restart fresh
docker compose down -v

---

Upgrading

git pull
docker compose build
docker compose up -d

Migrations run automatically on startup. If a migration fails:

docker compose exec backend python manage.py migrate

If the release notes mention PeerDB mirror changes, re-run init after migrations complete:

docker compose run --rm peerdb-init bash /setup.sh

Next Steps