The default docker-compose.yml runs one long-lived airmux container and Postgres. Before airmux starts, two short-lived
containers migrate the database and apply the shipped model catalog.
Install the airmux CLI on the machine you use to manage the instance.
Build from a checkout as shown below, or pull a published image from
ghcr.io/michel-tricot/airmux. Release tags use X.Y.Z, and latest moves to the most recent successful release.
Main CI also publishes tested candidates as sha-<commit>. For example, run docker pull ghcr.io/michel-tricot/airmux:latest
or replace latest with a release version. Use a digest for reproducible production deployment. Published images include
OCI version and source revision labels.
Start
The CLI reads provider keys from the checkout’s .env and stores missing credentials through the management API. The
application container does not receive the provider-key variables from that file.
For another local port:
Set these in .env, restart Compose, and pass the same URL to quickstart. For a public deployment, terminate TLS at a
reverse proxy and set AIRMUX_PUBLIC_URL to the exact HTTPS origin.
The packaged proxy replaces incoming forwarding headers and uses the configured public URL for the request scheme. API
and inference responses carry Cache-Control: no-store, including errors. The standalone data plane also applies these
headers; SSE responses carry no-store, no-transform, which the packaged proxy preserves. When an external TLS proxy sits in front of
the packaged proxy, its address is the observed client address. Client-specific throttling behind that edge requires an
explicitly configured trusted-edge integration; incoming client forwarding chains are never trusted by default. Keep the
split deployment’s control-plane port private to its Docker network.
Set a URL-safe POSTGRES_PASSWORD before the first start of a public installation. Changing the Compose variable later
does not rotate the password already stored by Postgres.
Startup and database changes
docker compose up runs the migration job first and the catalog job second. The airmux container starts only after both
jobs succeed. On later runs, migration checks the current schema revision and the catalog job reapplies the definitions
shipped with the selected image. To diagnose a failure:
Restarting the airmux container by itself does not run either job. The container does not use development mode, so the control
plane never changes the database schema or catalog while starting; it refuses to serve when the schema is out of date and
tells you to run the migration command.
State
docker compose down preserves both volumes. docker compose down -v deletes the complete installation.
Back up both volumes before an update, and do not use down -v unless permanent deletion is intended.
Update
Check out the intended release, take a backup, then build the image once and replace the stack:
The migration and catalog jobs use the same image as the serving container. The image defaults to the airmux role, which
starts the control plane, gateway, and webapp. The control plane verifies the migrated schema and creates its internal
gateway credential only when absent. Application processes run as UID 10001.
Docker initializes fresh named volumes from the image’s private state directories. Bind mounts and custom configured
paths must be writable by the selected container user; overriding the container user does not change the startup path.