airmux is the entry point for remote management, the inference gateway, and the control-plane server.
Local runtime commands do not require a saved login profile. Remote resource commands use the authentication context below.
Installation
With Python 3.13+ and uv:airmux is not on your PATH, run uv tool update-shell and restart your shell.
airmux --version prints the installed CLI version. Use airmux --help to see all commands.
Install command completion for the current shell with airmux completion. Use --shell to select
bash, zsh, fish, powershell, or pwsh instead of detecting it automatically.
For source checkouts and unreleased builds, see Development.
Local runtimes
Configuration resolution is
--config/-c, then AIRMUX_CONFIG, then per-runtime defaults; the
configuration reference names them.
Relative runtime paths and ${file:...} references resolve against their containing configuration file.
gateway init defaults to .airmux; control-plane init defaults to the current directory. --directory/-d selects another.
Initialization creates private keys, never prints their values, and refuses to overwrite any generated file. gateway init
copies the shipped taxonomy by default; --taxonomy PATH references an existing file without copying it. It finishes with
copyable start, readiness, and inference commands for a real model from the selected taxonomy, preferring one whose provider
variable is already set. Initialization writes ignore rules for generated keys and runtime secret state. validate checks local
configuration without contacting providers or the database.
For a standalone gateway, follow Gateway only. For a connected deployment with existing Postgres:
airmux gateway serve --config deployment/airmux.yml. The generated configuration shares a
private bootstrap key and file secret store between the planes. The same installation can run both services.
The control plane defaults to 127.0.0.1:8000 and the gateway to 127.0.0.1:8080; use --host and --port to change them.
The webapp and public reverse proxy are deployed separately. --console-url names their public origin; it does not start the webapp.
serve runs in the foreground. Control-plane startup creates a missing internal gateway credential, verifies the database is
at the expected migration revision, and does not change the model catalog. In production, run migrate and taxonomy
explicitly before serving. control-plane serve --dev applies migrations before starting its development reloader, but still
leaves taxonomy application explicit. The taxonomy command loads providers and models from a file; see
Models and providers. Startup does not create human accounts. gateway serve --dev
cannot be combined with multiple --workers. Local taxonomy and bundle reloads work without --dev.
control-plane taxonomy --file reads its path relative to the configuration file. Top-level catalog apply instead uses
the authenticated management API. control-plane owner is local recovery through database access; it promotes an existing
human account. control-plane fixtures is for development databases without human accounts and prints access details through
--format table|json|text.
Containers invoke these same runtime commands. Update containers by replacing the image; the CLI never updates packages
inside a running container.
Authentication and context
airmux login uses a browser device flow and saves a private profile to ~/.airmux/config.toml. Override the file with AIRMUX_CLI_CONFIG.
--dev where supported, environment, active profile, then local default.
Output formats
Commands returning resource data accept-f/--format table|json|text. Table is the interactive default, JSON is
intended for automation, and text is tab-separated.
Paginated list commands request 50 results by default. Use --limit 1..200 to choose the page size and --all to follow
cursors until every page has been fetched. Without --all, output contains only the first page. Configuration and status
commands always return their complete set and do not expose pagination flags. events tail walks every page back to the
newest event it has already shown, so a burst larger than one page is not skipped.
airmux commands is the source-backed inventory for the installed CLI version.
Top-level help groups commands by task:
Each command group’s help keeps its subcommands in one flat list.
Getting started and connection commands
Organization and workspace commands
Gateway resource commands
Run
airmux <group> <command> --help for the exact options installed on your machine.
Define policy rules inline in the JSON configuration’s definition.rules array, with one match and one action per rule.
Pass the file to airmux policies create CONFIGURATION or airmux policies update POLICY_ID CONFIGURATION.
See Create a workspace policy for a complete example.