Deploy with Docker Compose
The commands that stand Agent Fleet up with Docker Compose on one Linux host, up to the first administrator signing in. What each step decides is in Install Agent Fleet. Open this page when you type the commands.
How it works
Section titled “How it works”| What you do | What happens |
|---|---|
Create .env and write the secrets, DOCKER_GID, the public URL and the IdP |
The Control Plane starts with these values |
| Provide the workspace image (build or pull it) | The Control Plane can start a workspace per member with docker run |
Start it with docker compose up -d |
The Control Plane (cp) and Caddy run, and Caddy obtains the TLS certificate |
Sign in with a SUPER_ADMIN_EMAILS account |
That account becomes the deployment administrator and can launch a workspace |
You work in deploy/compose/ (or, from a release bundle, the extracted directory).
What is in this directory
Section titled “What is in this directory”| File | Purpose |
|---|---|
docker-compose.yml |
The cp (Control Plane) and caddy (automatic TLS) services |
Caddyfile |
Reverse proxy and Let’s Encrypt (ACME). The tls internal self-signed fallback is here too |
.env.example |
All configuration. Copy it to .env |
backup.sh, restore.sh |
Backup and restore (Back up and restore) |
load-images.sh |
Imports images from a local tar. Only for hosts that cannot reach a registry (Install into a closed network) |
release.sh |
Builds a versioned release bundle. For maintainers |
docker-compose.macos.yml |
The overlay for a Mac (Run on an Apple Silicon Mac) |
Released images are published to GHCR.
- They are
ghcr.io/k-k1/agent-fleet/control-plane:<version>andghcr.io/k-k1/agent-fleet/workspace:<version> REGISTRYandVERSIONin.envresolve them. The packages are public, so pulling needs no registry login- To pull from an internal mirror, point
REGISTRYat it
Before you start
Section titled “Before you start”| What you need | Notes |
|---|---|
A Linux host with Docker (Engine and docker compose) |
An Apple Silicon Mac works for one person (Run on an Apple Silicon Mac) |
| A public domain with a DNS A / AAAA record pointing at this host | For TLS. Internal only? Use tls internal in the Caddyfile |
| An IdP client for sign-in | A Google OAuth 2.0 web client, or an OIDC app at Entra ID, Okta, Keycloak, Auth0, Cognito or GitLab. You register one redirect URI however many you use |
| Agent seats | Each member signs in with their own seat from the Console after the first launch. Company Team / Enterprise seats are recommended over personal Pro / Max |
(For agy) a CPU that exposes RDRAND |
“The Antigravity CLI and RDRAND” below |
An IdP that only speaks SAML (HENNGE One, TrustLogin, CloudGate …) goes behind oauth2-proxy or Keycloak, with AUTH=proxy.
The Antigravity CLI and RDRAND
Section titled “The Antigravity CLI and RDRAND”agy (the Antigravity CLI) is a FIPS build that aborts at startup without the CPU’s RDRAND instruction. Check with grep -w rdrand /proc/cpuinfo.
- Where the kernel has withdrawn the instruction (seen on AMD Ryzen Embedded, whose RDRAND returns a constant), the Agent masks it out of OpenSSL’s CPU detection and runs agy anyway. Its randomness then comes from the kernel rather than the CPU, and the Console’s agy card says so
- A deployment that requires the FIPS module’s own entropy path sets
AF_AGY_RDRAND_MASK=0.agyis then hidden from the agent selector
Starting from a published release
Section titled “Starting from a published release”The install-compose.sh helper in the distribution repo fetches, verifies and extracts the bundle and pulls the images from GHCR.
It leaves you at the cp .env.example .env step of step 1 below. The steps on this page are the manual (or from-source) path.
1. Configure and start from source
Section titled “1. Configure and start from source”Create DATA_DIR so that the user the Control Plane runs as (uid 1000, user: "1000:1000" in docker-compose.yml) can write it. An ordinary user cannot create the default /srv/agent-fleet/data, so 4) below creates it with sudo and hands it to 1000:1000.
cd deploy/composecp .env.example .env# 1) generate secrets and put them in .env:head -c 32 /dev/urandom | base64 # -> AF_MASTER_KEY (store a copy in a vault!)head -c 32 /dev/urandom | base64 # -> AF_COOKIE_SECRET# 2) set DOCKER_GID to the host docker group:getent group docker | cut -d: -f3 # -> DOCKER_GID# 3) fill in PUBLIC_DOMAIN / PUBLIC_BASE_URL / your IdP (GOOGLE_OAUTH_* and/or# AF_OIDC_*) / AF_OAUTH_ALLOWED_DOMAINS / SUPER_ADMIN_EMAILS / DATA_DIR in .env# 4) create DATA_DIR owned by uid 1000, the user the CP runs as (the default# /srv/agent-fleet/data needs sudo):DATA_DIR="$(grep -E '^DATA_DIR=' .env | cut -d= -f2)"sudo mkdir -p "$DATA_DIR" && sudo chown 1000:1000 "$DATA_DIR"
# 5) build the per-user workspace image (compose builds only the CP; the CP# launches workspaces from WS_IMAGE, agent-fleet/workspace:dev by default):docker build -t agent-fleet/workspace:dev ../../workspace
docker compose up -d --build # from sourcedocker compose logs -f cp- Store
AF_MASTER_KEYin a password vault the moment you generate it. It is in neitherDATA_DIRnor the backups (Handle the deployment keys) - A wrong
DOCKER_GIDgives “permission denied” on the docker socket .env.exampleitself explains each variable. What to choose is in steps 1–4 of Install Agent Fleet
2. Start from the published release images
Section titled “2. Start from the published release images”To run a published release instead of building, leave REGISTRY, VERSION and WS_IMAGE at the values the bundle ships with, skip 5) of step 1 (the image build), and pull.
docker compose pull # cp + caddydocker pull "$(grep -E '^WS_IMAGE=' .env | cut -d= -f2)" # workspace (see below)docker compose up -dThe workspace image is not a compose service. The Control Plane starts it per member with docker run, so docker compose pull does not fetch it.
- You need not pull it up front: the first workspace start pulls it on demand
- Pulling it up front spares whoever presses Start first a wait of several minutes
3. Write the sign-in IdP
Section titled “3. Write the sign-in IdP”The .env keys and what to create on the IdP’s side are on each IdP’s page.
| IdP | Page |
|---|---|
| Sign in with Google | |
| Microsoft Entra ID | Sign in with Microsoft Entra ID |
| GitHub | Sign in with GitHub |
| Okta, Keycloak, Auth0, Cognito, GitLab | Sign in with another OIDC IdP |
Whichever IdP you use, the redirect URI you register is this one:
https://<PUBLIC_DOMAIN>/oauth2/callbackGitHub’s and Bitbucket’s “Connect via OAuth” for cloning repositories is not in .env: a tenant administrator registers it in the Console (Choose the OAuth apps for integrations).
4. Sign in as the first administrator
Section titled “4. Sign in as the first administrator”- Open
https://<PUBLIC_DOMAIN> - Sign in with an account you listed in
SUPER_ADMIN_EMAILS - Launch a workspace
SUPER_ADMIN_EMAILSis read once at startup and is the only source of truth. Removing an address and restarting also takes the deployment administrator role away.env.examplestarts withAF_PROVISION=invite: nobody else gets a workspace until an administrator adds them. Someone who was added signs in without also being inAF_OAUTH_ALLOWED_*- How to decide tenants, members and each tenant’s sign-in page (
<PUBLIC_BASE_URL>/login/<slug>) is in Choose the tenant and provisioning model - How to remove someone is in Revoke access and hand over super_admin
When it goes wrong
Section titled “When it goes wrong”| Symptom | Where to look |
|---|---|
| The Control Plane does not start | docker compose logs cp. Does curl -s http://127.0.0.1:8099/healthz print ok? |
| “permission denied” on the docker socket | Does DOCKER_GID match getent group docker? |
| Every sign-in is refused | Every allowlist is empty and nobody has been invited yet (Cannot log in) |
| Workspaces cannot reach the public URL | When workspaces cannot reach the CP |
Other symptoms are in Find the cause from the symptom.
Related
Section titled “Related”For agents
Send this prompt to your agent to read this page.
Read https://agent-fleet.org/docs/operate/compose/install/index.md