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
the local default. Credentials resolve from AIRMUX_MANAGEMENT_KEY, then the active profile. The target organization
resolves from a command’s --organization, AIRMUX_ORGANIZATION_ID, saved selection, then the active profile. The workspace
resolves from --workspace, saved selection, then the active profile when its organization matches the effective organization.
organizations switch and workspaces use save targets independently of credentials. Switching organizations clears the saved
workspace. A saved workspace from another organization fails before a request; pass --workspace or select a new one.
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
You can also set up an instance through the web app. See the quickstart for both setup paths.Organization and workspace commands
Set or change a user’s role at each scope:
owner, auditor, data_plane, or none to remove the role. Organization roles are
owner, admin, member, or data_plane. Workspace roles are admin, member, or viewer.
Organization commands accept --organization <organization-id> and otherwise use the effective organization. Workspace commands
also accept --workspace <slug-or-id> and otherwise use the selected workspace.
The membership commands assign a role even when the user is not yet a member, just like members add.
All three commands accept -f table|json|text and enforce the existing authorization and owner protections.
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.
Use airmux policies enable POLICY_ID or airmux policies disable POLICY_ID to change activation without a file.
Both commands show the updated policy, including enabled. policies status reports budget spending.
For organization-wide provider credentials, use --organization-wide; --organization selects the target organization.
See Create a workspace policy for a complete example.