Container images

In this page

Every Future AGI image is published to Docker Hub under futureagi/, built from the future-agi repository by its release workflow, and follows the same conventions: one tag scheme, the same OCI labels, a digest-pinned base, a HEALTHCHECK that probes the service’s real health endpoint, and a documented user. This page lists every image, what it runs and how big it may be, and the conventions they share, so you can pin, verify, probe and rebuild them.

Images at a glance

Setups: Standalone is the default install (./bin/install, docker-compose.yml). Distributed runs one container per service (./bin/install --distributed, docker-compose.distributed.yml). Helm is Distributed on Kubernetes and uses the same images.

Size budget: the most a docker pull may download (compressed MB, 10^6 bytes, per architecture), from scripts/image_size_budget.json. A release checks it on every architecture before it moves a tag.

A fresh Standalone install downloads standalone, postgres:16 and clickhouse/clickhouse-server:25.3-alpine: 884 MB at most (measured 803).

Backend variants

futureagi/Dockerfile.oss builds the backend in two variants, chosen by one build argument, IMAGE_VARIANT:

Both run the same code and dependency versions (from uv.lock). What the slim variant leaves out shows up in a Standalone install as:

• Hosted agent runs on Daytona or E2B answer 501 sandbox_sdk_missing, and runs from a GitHub source 501 git_unavailable.
• The Vertex AI partner models (Model Garden, Gemma, Claude, Llama and Mistral on Vertex) are hidden from the model picker.
• SERVICE_TYPE=flower and the RabbitMQ channel layer are unavailable.
• Error localization runs its original backend (ERROR_LOCALIZER_BACKEND=legacy, which cannot localize simulation call audio) instead of the Claude Agent SDK one.
• An audio upload in an exotic codec (AV1, WavPack, ProRes) fails with “Decoder not found”.

IMAGE_VARIANT only sets the defaults of the per-feature build arguments (Build arguments); one passed explicitly wins. A Standalone install that needs any of the above can build its app image from the default variant, from a checkout of the same tag (the image’s bootstrap runs that backend’s manage.py bootstrap_install):

docker build -t futureagi/standalone:local \
  --build-arg BACKEND_IMAGE=futureagi/future-agi:vX.Y.Z deploy/standalone

Or build a slim backend with just the pieces it needs, then the app image on top of it:

docker build -f futureagi/Dockerfile.oss --build-arg IMAGE_VARIANT=slim \
  --build-arg EXTRAS=sandbox --build-arg WITH_GIT=true -t futureagi/future-agi:local futureagi
docker build -t futureagi/standalone:local \
  --build-arg BACKEND_IMAGE=futureagi/future-agi:local deploy/standalone

Then set FUTURE_AGI_VERSION=local in .env and run docker compose up -d.

Tags

• A release builds every architecture, checks it, and only then points all three tags of an image at one multi-architecture manifest (build-image-multiarch.yml), so a tag never names a half-published image.
• A version with a suffix (v1.43.0-rc1, ad-hoc builds from the per-image release-*.yml workflows) gets that one tag; vX.Y and latest do not move.
• futureagi/code-executor-base takes exactly one immutable tag per version (base-image-publish.yml refuses to overwrite one); code-executor pins it.
• Tags that never reach Docker Hub: :local (./bin/install --from-source, ./bin/dev), :e2e-local (./bin/e2e), :ci (CI’s local registry).

The installers choose the tag with FUTURE_AGI_VERSION in .env (empty means latest); Distributed also reads FRONTEND_VERSION, AGENTCC_GATEWAY_VERSION, FI_COLLECTOR_VERSION, SERVING_VERSION and CODE_EXECUTOR_VERSION. See Images in the configuration reference.

Labels

Every image carries the OCI annotation labels below. version, revision and created come from the VERSION, REVISION and CREATED build arguments, which the release workflows pass and each Dockerfile declares as its last instructions, so a new value changes only the image configuration and never invalidates a cached layer. A local build without them says dev and unknown.

Extra labels: ai.futureagi.<component>.image on standalone (the backend, frontend, fi-collector, agentcc-gateway, Temporal and MinIO images it was assembled from, with digests on a release), ai.futureagi.sdk.version and ai.futureagi.backend.image on the simulation runner, and ai.futureagi.torch-backend (cpu or cu124) on serving.

Read them without pulling the image:

docker buildx imagetools inspect futureagi/standalone:latest --format '{{json .Image}}' \
  | jq '."linux/amd64".config.Labels'

Or from a pulled image:

docker image inspect futureagi/standalone:latest --format '{{json .Config.Labels}}' | jq

Verifying an image

services:
  app:
    image: futureagi/standalone:v1.43.0@sha256:<digest>

Health checks

Each long-running image declares a Docker HEALTHCHECK, which docker ps shows and docker compose up --wait waits for. Kubernetes ignores it: point the pod probes at the same endpoints.

• The backend’s /health/ answers 503 while an embedded Temporal worker is down (tfc/asgi.py), so the probe covers the worker too. The probe sends the first non-wildcard ALLOWED_HOSTS entry as its Host header, so tightening ALLOWED_HOSTS does not fail it.
• fi-collector and agentcc-gateway have no shell, so they ship a 1.8 MB static probe, /usr/local/bin/healthcheck (its source is in both Dockerfiles).
• HEALTHCHECK_URL (a URL, or for the backend a comma-separated list) moves the probe of future-agi, fi-collector and agentcc-gateway, for example when the gateway listens on another port. Set it in that service’s environment:, not in .env, which several services read.
• No probe goes through HTTP_PROXY or HTTPS_PROXY.

Kubernetes probe targets:

Users

To run the backend as a non-root user: /app/backend, its logs, media and static directories, and the directories the app writes under /app/backend/tfc (logs, which the settings create on import, metadata and saml_logs for SAML, compare for dataset comparisons) belong to appuser (1000), so:

• Compose: add user: "1000:1000" to the backend services (docker-compose.distributed.yml). Docker 20.10 and later let any user bind :80 inside a container.
• Kubernetes: runAsUser: 1000, runAsGroup: 1000, fsGroup: 1000 (volumes such as a logs volume become writable), and the safe sysctl net.ipv4.ip_unprivileged_port_start=0 for port 80.

Files you mount into a non-root image (the gateway’s config and Google credentials, for example) must be readable by its user: mode 0644, or a Kubernetes Secret or ConfigMap with its default mode. File sinks you configure (a disk cache or file audit log in the gateway) need a mounted directory that user can write.

Stopping

Every image stops on SIGTERM, except frontend (SIGQUIT: nginx finishes the requests in flight). Give the containers that drain work time to do it: standalone 60 s (the API drains its Temporal worker for up to 50 s), the simulation runner more than TEMPORAL_GRACEFUL_SHUTDOWN_TIMEOUT (compose sets 330 s), Temporal workers TEMPORAL_GRACEFUL_SHUTDOWN_TIMEOUT plus a margin.

Base images

Every base is set by an ARG near the top of its Dockerfile, pinned by digest, so a rebuild of the same commit reuses the same layers and an upgrade downloads only what changed.

Deliberately not pinned by digest, each explained in its Dockerfile:

• golang:1.24-alpine and golang:1.26-alpine float on the minor version: build stages only, and Go patch releases carry standard-library security fixes that are compiled into the binaries.
• standalone’s component images and the simulation runner’s backend default to :latest for a quick local build; a release passes this release’s images pinned by digest (the -slim backend to standalone, the default one to the simulation runner).
• code-executor pins futureagi/code-executor-base by an immutable version tag; the digest is added once that version is published.

A weekly check flags a pinned tag that has moved, for example after a Debian security update, and the new digest lands in a pull request like any other change.

Build arguments

Standard, on every image:

Per image:

Build the images yourself

From a checkout of the future-agi repository, the installers build every image and install from them:

./bin/install --from-source                 # slim backend, frontend, fi-collector, gateway, then standalone, as :local
./bin/install --distributed --from-source   # default backend, frontend, fi-collector, gateway, as :local
./bin/dev                                   # the same images, with hot reload

Or build one image at a time:

docker build -f futureagi/Dockerfile.oss -t futureagi/future-agi:local \
  --build-arg REVISION="$(git rev-parse HEAD)" futureagi    # add --build-arg IMAGE_VARIANT=slim for the slim variant
docker build -t futureagi/frontend:local frontend
docker build -t futureagi/fi-collector:local fi-collector
docker build -t futureagi/agentcc-gateway:local agentcc-gateway
docker build -f futureagi/model_serving/Dockerfile.oss -t futureagi/serving:local futureagi/model_serving
docker build -f futureagi/code-executor/Dockerfile.base -t futureagi/code-executor-base:v1.1.0 futureagi/code-executor
docker build -t futureagi/code-executor:local futureagi/code-executor

./bin/dev and the development workflow are covered in Local development.

Dive deeper