Installation

Install a self-hosted Future AGI instance with Docker Compose.

Docker Compose is the supported way to run a self-hosted Future AGI instance.

In this page

Confirm your host meets the requirements first, then ./bin/install does the rest:

Bootstraps your .env
Brings up the stack
Waits for the backend health check
Prompts you to create the first user

First boot pulls the app images from Docker Hub and builds the small fi-collector image from source, so give it a few minutes the first time.

📝

TL;DR

Run git clone https://github.com/future-agi/future-agi.git && cd future-agi && ./bin/install, then open http://localhost:3000.

Install

Clone the repository and run the installer

git clone https://github.com/future-agi/future-agi.git
cd future-agi
./bin/install          # Windows: bin\install.ps1

The stack boots fine against an empty .env, so you can take the defaults for a local trial.

By default the installer brings up the standard stack (around 12 containers). Add --full to include the PeerDB CDC stack (around 22 containers) that populates the analytics views.

Create your first user

The installer prompts you at the end. If you passed --skip-user-creation, create the account from the CLI instead:

docker compose exec backend python manage.py create_user

You will be asked for an email, full name, and password. To script it, pass them inline:

docker compose exec backend python manage.py create_user \
  --email you@example.com \
  --name "Your Name" \
  --password yourpassword

Open the app

Installer flags

Flag	What it does
`--full`	Add the PeerDB CDC stack (around 22 containers) so the analytics views populate
`--skip-user-creation`	Skip the first-user prompt; create the account later with `create_user`
`--no-up`	Bootstrap `.env` only, without starting the stack
`--wipe-volumes`	Remove stale project volumes before starting (destroys existing data)
`--new-instance`	Start a fresh instance when existing volumes are detected

Note

Apple Silicon and arm64 hosts. Prebuilt images are linux/amd64. On M-series Macs they run under Rosetta 2 (auto-enabled on Docker Desktop 4.16+), which is fine for evaluation with a 20 to 50 percent performance cost. For native arm64, build locally with docker compose build instead of pulling. On Linux arm64 such as Graviton, install qemu-user-static.

Install without the script

The installer is a convenience wrapper, not a requirement. To run the same steps by hand:

cp .env.example .env       # optional; an empty .env works for local
docker compose up -d

Then create the first user with the same create_user command shown above.

Verify the stack

Check that every service is healthy before you log in. Under-provisioned RAM is the most common reason the backend never finishes booting, so confirm the requirements if it stalls.

docker compose ps                 # every service should read "running" or "healthy"
docker compose logs -f backend    # watch for errors while it boots
curl http://localhost:8000/health/

The instance is ready when /health/ returns OK. That’s the same check ./bin/install polls while it waits for the backend.

Everyday operations

A short reference for the commands you will use most:

# Tail 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 the stack (data persists in named volumes)
./bin/uninstall                # or: docker compose down

# Wipe all data and start clean
./bin/uninstall --wipe-data    # or: docker compose down -v

# Remove everything: containers, volumes, .env, and built images
./bin/uninstall --purge

Other ways to run it

Mode	Command	Use it for
Standard (default)	`docker compose up -d`	Local evaluation, team installs, and VM self-hosting
Development	`docker compose -f docker-compose.yml -f docker-compose.dev.yml up`	Contributing to Future AGI: hot reload, per-queue workers, host-accessible database ports, and the Temporal UI
Frontend only	`docker compose -f docker-compose.frontend.yml up -d`	Pointing a local UI at a backend that runs elsewhere

Warning

For a frontend-only deploy, set VITE_HOST_API to the backend URL the browser can reach. It is applied when the container starts, so changing it needs only a restart of the frontend container, not a rebuild.

Dive deeper

Environment variables

Set provider keys, secrets, and runtime flags in .env

System configuration

Tune the gateway, PeerDB, and Temporal workers

Was this page helpful?

Questions & Discussion