Development

Clone and install

Install Python 3.13+, uv, Bun, and Docker with Compose. The development stack uses ports 5432, 8000, 8080, and 5000; stop any service already using them. Clone the repository and install its dependencies:

git clone https://github.com/michel-tricot/airmux.git
cd airmux
uv sync --all-packages --frozen
bun install --frozen-lockfile
cp .env.example .env
docker compose -f docker-compose.dev.yml up -d --wait

Start the development environment

Load the development catalog:

uv run airmux control-plane taxonomy --file taxonomy/taxonomy.yml

Start each service in its own terminal:

Service	Command	Address
Control plane	`uv run airmux control-plane serve --dev`	`http://127.0.0.1:8000`
Gateway	`uv run airmux gateway serve --config airmux.yml --dev`	`http://127.0.0.1:8080`
Webapp	`bun run dev`	`http://127.0.0.1:5000`

Finish local setup through the webapp origin:

uv run --package airmux airmux quickstart --url http://127.0.0.1:5000

The development control plane applies migrations and creates .airmux/dataplane.key when needed. Keep that key with its local database.

Develop and verify

Create a branch for your change. Add a behavior test, make the change, and run the checks for the affected area. For a full local check:

uv run ruff format .
uv run ruff check .
uv run ty check .
uv run lint-imports
uv run pytest -n auto
bun run format:check
bun run lint
bun run typecheck

Control-plane unit tests can run without Docker using uv run pytest apps/control-plane/tests/unit. Integration tests use the Postgres service started above. For inference request-path changes, run uv run pytest tests/acceptance/full_stack/scenarios and verify a real request through the local gateway.

Contribute a change

Before editing, read CONTRIBUTING.md, AGENTS.md, and any relevant design record. Update generated contracts when their source changes, and commit generated outputs with the change. Open a pull request against main with a concise summary of user impact and the checks you ran. Draft and ready pull requests run the same fast checks. Main CI runs the broader checks after merge. Address review feedback and merge after the required CI and security checks pass.

Publish a release

The root VERSION file is the public package version. Publish Release requires the full SHA of the version pull request’s merge commit on main. It checks Main CI and Security for that exact commit. The other workspace projects stay at 0.0.0.

Checklist

Run Actions → Prepare Release on main, then merge its pull request
Wait for Main CI and Security to pass
Run Actions → Publish Release on main with the version PR’s merge commit SHA; wait for it to finish
Check the GitHub release, PyPI package, and GHCR version and latest tags

Prepare Release opens a pull request that changes VERSION. Publish Release confirms that the supplied commit changed VERSION and has not already been tagged. It uses the validated Python and container artifacts from that commit’s successful Main CI run; it does not rebuild them. It checks installation and live providers before creating the tag, then publishes and verifies the package and image. The release environment supplies provider credentials and RELEASE_GITHUB_TOKEN; PyPI uses its trusted publisher for release.yml.

If a release fails

Failed stage	Action
Main CI or Security	Fix the failure on a PR. If the release source changed, prepare a new version, wait for its checks, then dispatch Publish Release
`prepare`	Confirm the full SHA is the version pull request’s merge commit on `main`, the version tag is unused, and both main checks passed; then dispatch Publish Release again
`installation` or `live-providers` before the tag	Retry transient failures. If the release source must change, fix it on a PR and prepare a new version before dispatching again
After the tag or during publication	Rerun failed jobs on the original Publish Release run while its Main CI artifacts are available. Keep the tag on its original commit
After PyPI or GHCR publication	Inspect the published version and digest, then rerun failed verification or announcement jobs on the original run. If the source must change, prepare a new version; published package bytes and release tags cannot be replaced

Install a local build

Build and install an unreleased checkout, then run its portable installation smoke test outside the repository:

(
set -e
./scripts/build-python-distribution.sh
uv tool install --reinstall dist/airmux-*.whl
smoke_dir="$(mktemp -d)"
export UV_TOOL_DIR="$smoke_dir/tools"
export UV_TOOL_BIN_DIR="$smoke_dir/bin"
uv tool install --python 3.13 dist/airmux-*.whl
uv venv --python 3.13 "$smoke_dir/runner"
uv pip install --python "$smoke_dir/runner/bin/python" pytest httpx pyyaml
mkdir -p "$smoke_dir/tests/installation/portable" "$smoke_dir/tests/acceptance"
cp tests/installation/portable/*.py "$smoke_dir/tests/installation/portable/"
cp tests/installation/installation_support.py "$smoke_dir/tests/installation/"
cp tests/acceptance/process_harness.py "$smoke_dir/tests/acceptance/"
cd "$smoke_dir"
AIRMUX_INSTALL_BIN="$UV_TOOL_BIN_DIR/airmux" AIRMUX_INSTALL_PYTHON=3.13 \
  "$smoke_dir/runner/bin/python" -I -m pytest -o pythonpath=. tests/installation/portable
)

The airmux command is then available outside the repository.

Get started

Use the platform

Deploy and operate

Concepts

Contributing

Clone and install

Start the development environment

Develop and verify

Contribute a change

Publish a release

Checklist

If a release fails

Install a local build

​Clone and install

​Start the development environment

​Develop and verify

​Contribute a change

​Publish a release

​Checklist

​If a release fails

​Install a local build

Clone and install

Start the development environment

Develop and verify

Contribute a change

Publish a release

Checklist

If a release fails

Install a local build