Installation

This page covers installing with Docker Compose. For Kubernetes, see Helm. To pick between them, see Choose a setup.

In this page

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

1. Creates .env from .env.example, or on a re-run merges in new keys from .env.example without changing your values. On a fresh install it generates the secrets and records the setup.
2. Checks the host ports, the Docker VM’s memory, CPUs and architecture, and that Docker can see the checkout.
3. Pulls the images (about 800 MB for Standalone), or builds them with --from-source.
4. Starts the stack with docker compose up -d.
5. Waits until the API (and, in Standalone, the UI) answers, then creates the first account it asked you for. Before it asks, it shows what deployment telemetry sends and how to opt out.

It writes a log of the run to install-YYYYMMDD-HHMMSS.log in the repository root, and exits 1 when the stack came up but the first account could not be created.

Install

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

docker compose exec app python manage.py create_user       # Standalone
docker compose exec backend python manage.py create_user   # Distributed

Installer flags

bin/install and bin\install.ps1 take the same options, except --new-instance, which has no PowerShell equivalent. The installer never moves an install to another setup: --distributed is refused for a project that holds a Standalone install, even with --force.

Install without the script

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

cp .env.example .env
docker compose up -d       # Standalone

For Distributed, uncomment COMPOSE_FILE=docker-compose.distributed.yml in .env first, or pass -f docker-compose.distributed.yml to every command.

Then create the first account:

docker compose exec app python manage.py create_user       # Distributed: backend

Verify the stack

Check that every container is up before you sign in:

docker compose ps                  # every container should read "running" or "healthy"
docker compose logs -f app         # Distributed: docker compose logs -f backend
curl http://localhost:8000/health/

In Standalone, docker compose logs -f app starts with a summary of the configuration: setup, version, URLs, LLM providers by name, email, telemetry, the code-eval sandbox and model serving. It never prints secret values. It ends with Future AGI is ready in ....

The instance is ready when /health/ returns OK. That’s the same check ./bin/install polls while it waits for the API. Troubleshooting covers anything that stays red.

Everyday operations

Data lives in named Docker volumes and survives restarts and upgrades. bin/uninstall reads the setup and project name from .env, so the same commands work for both setups. Images built by --from-source are shared by every checkout on the machine, so --purge asks about them separately, and -y keeps them.

# Follow the logs
docker compose logs -f app         # Distributed: docker compose logs -f backend worker

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

# Upgrade to the latest release: back up first, then
git pull && ./bin/install

Take a backup before you upgrade: migrations run on start, and a rollback does not reverse them. The full procedure, pinning and rollback are in Upgrades & rollback. On an install made before Standalone became the default, run ./bin/install after git pull, not a plain docker compose up -d, which would start the wrong stack: see Upgrading older installs.

To reset a password without email, see Reset a password.

Switch setups

There is no supported way to move an install, data included, from one setup to another. That includes growing Standalone into Distributed or Helm: the only way is a fresh install, so if you expect to outgrow one host, start on Distributed or Helm.

The installer never switches an install that has data. A re-run keeps the setup .env records, and --distributed stops with an error for a project that holds a Standalone install. An install made before Standalone became the default is kept on Distributed; see Upgrading older installs.

To switch, back up what you need, then start fresh:

# Standalone to Distributed
./bin/uninstall --wipe-data
./bin/install --distributed

# Distributed to Standalone
./bin/uninstall --wipe-data
# delete the COMPOSE_FILE= line from .env
./bin/install

--wipe-data keeps .env, so the new install reuses its secrets. To try the other setup without touching this one, run it as a separate project: a second checkout with another COMPOSE_PROJECT_NAME and other ports in its .env.

To move to Kubernetes, install the chart (see Helm), then remove the Compose install with ./bin/uninstall --wipe-data. The chart does not read .env: carry what you need over in the chart’s values.

Other ways to run it

Dive deeper