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 every image from Docker Hub, nothing is built locally, 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.

Note

On arm64, do this first. The backend image (futureagi/future-agi) is amd64 only. On Linux arm64 such as Graviton, install qemu-user-static before you install, or backend and worker won’t start at all. On Apple Silicon they run under Rosetta 2 automatically. Details in the note below the steps.

Install

Clone the repository and run the installer

git clone https://github.com/future-agi/future-agi.git
cd future-agi
./bin/install

On Windows, run bin\install.ps1 instead. The other bin/ scripts have .ps1 equivalents too.

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 of 13 services. Add --full to include the PeerDB CDC stack, taking you to 23. See Profiles for what each one adds.

Create your first user

The installer prompts you at the end for an email, full name, and password. That’s the whole step on the default path.

If you passed --skip-user-creation, create the account from the CLI instead:

docker compose exec backend python manage.py create_user

It asks for the same three values. 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

On a fresh install the app opens a short setup wizard before the sign-in screen, where you pick a launch mode and watch it probe your services. It runs once per browser.

Installer flags

Flag	What it does
`--full`	Add the PeerDB CDC stack, taking the stack from 13 services to 23
`--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. Five of the six first-party images ship linux/arm64 alongside linux/amd64, so they run native. The exception is futureagi/future-agi, which is amd64 only and backs both backend and worker. On M-series Macs those two run under Rosetta 2 (auto-enabled on Docker Desktop 4.16+), which is fine for evaluation at a 20 to 50 percent performance cost on those containers. On Linux arm64 such as Graviton, install qemu-user-static so they can start at all.

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:

docker compose exec backend python manage.py create_user

Verify the stack

Check that every service is healthy before you log in. The failure you’re most likely to hit is the backend never printing Application startup complete and the container restarting in a loop, which is almost always under-provisioned RAM: confirm the requirements if you see that, and Troubleshooting covers anything else that comes up red.

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. Upgrades have their own page, Upgrades & rollback.

# 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

# Update to a new release (full procedure: Upgrades & rollback)
docker compose pull && docker compose up -d

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

# Also remove .env, logs, and any locally built images
# (pulled images stay; remove those with docker rmi)
./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 in .env 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.

Questions & Discussion