Requirements

In this page

Check four things before you install:

• A host that meets the sizing for the setup you choose
• The required software: Docker and Git, or Kubernetes and Helm for the chart
• Privileged containers, only if you run Distributed’s code-executor, Standalone’s optional sandbox profile or Helm’s optional code sandbox
• Host ports that are free, or remapped

Get these right and the Installation run works on the first try.

Hardware

Size the host for the setup you choose. For Docker Compose, memory means the Docker VM’s memory, not the host’s: on macOS and Windows, Docker runs in a VM and the stack gets only what that VM has.

The Helm column is an evaluation install with bundled datastores. Production on Kubernetes is sized per service: see Install for production. Disk use grows with your data from the numbers above.

What a fresh Compose install downloads, compressed:

Standalone and Distributed share no backend image layers, so switching between them downloads the backend again. Upgrades download only the layers that changed.

./bin/install measures the Docker VM’s memory and CPUs with a small probe container before it starts anything. Below the minimum it stops and prints the fix for your runtime (--force continues anyway); below the recommended size it warns. Re-running the installer on an existing Distributed install only warns, whatever the size. Standalone idles at about 1 GB. The optional ml profile (model serving) adds a large image and a few GB of memory once its models load, and ./bin/install --from-source wants an 8 GB VM for the frontend build.

Software

Compose v2.24 is a hard floor, not a recommendation: docker-compose.yml declares its env files with the long path / required form, which older Compose can’t parse. On v2.23 or below the stack fails at parse time, before a single image is pulled.

Run Docker with Docker Desktop, Colima or OrbStack on macOS, Docker Desktop on Windows, or Docker Engine on Linux. The installer warns when it finds only the legacy docker-compose v1. For Kubernetes you need a 1.27+ cluster and Helm 3.10+ or Helm 4 instead: see Helm.

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

sudo apt-get install -y docker.io docker-compose-v2 git
sudo systemctl enable --now docker
sudo usermod -aG docker $USER   # log out and back in

[wsl2]
memory=4GB
processors=2

wsl --shutdown

Platform compatibility

Privileged containers are needed only by Distributed’s code-executor, Standalone’s optional sandbox profile and Helm’s optional code sandbox. A default Standalone install runs Python code evals in an unprivileged sandbox inside its app container.

Every Future AGI image is published for linux/amd64 and linux/arm64, each built natively, so the stack runs native on Apple Silicon and on Linux arm64 hosts such as AWS Graviton. Two images are linux/amd64 only: the CUDA variant of model serving (-gpu tags) and the voice simulation runner of Distributed and Helm. Releases before Standalone became the default published an amd64-only backend image, which Docker runs under emulation on arm64 (Rosetta 2 on Docker Desktop 4.16+, qemu-user-static on Linux): slower, with a first boot that can take 20+ minutes. ./bin/install --from-source always builds native images. Container images lists the architectures and download size of every image.

Network ports

Make sure these host ports are free before you install, or remap any that collide. Every published port reads from .env with a built-in default (for example ${FRONTEND_PORT:-3000}), so you can change one without touching the Compose file. Anything on 127.0.0.1 is reachable from the host but not from the network.

Standalone

Nothing else is published: no Postgres, ClickHouse, Redis, Temporal or code-eval sandbox port, and the ml and sandbox profiles publish none either.

Distributed

The code executor listens on 127.0.0.1 only because it runs any code it is sent, without authentication. The two rows tagged with a profile run only under that profile and are free otherwise.

On Kubernetes the chart publishes no host ports: its services talk over in-cluster Services, and you choose how to expose the UI and API. See Helm.

Watch 4317 and 4318 in particular: they are the default OTLP ports, so they collide with any other OpenTelemetry collector already on the host. 4318 is where the SDK sends your traces (FI_BASE_URL=http://localhost:4318).

To find a collision before you install, check the ports you care about:

lsof -i :3000 -i :8000 -i :8090 -i :4317 -i :4318    # anything listed is already taken

./bin/install checks every port the chosen setup publishes before it starts the stack. For a taken port it offers the next free one and writes it to .env (with -y it takes it without asking). Moving BACKEND_PORT also rewrites VITE_HOST_API when that is unset or points at localhost. Without the installer, Compose fails at startup with a bind error naming the port: set the key in .env yourself.

Dive deeper