Skip to main content
Use this guide to change the source. To run airmux without a development toolchain, follow the Docker quickstart.

Clone and install

Install Python 3.13+, uv, Bun, and Docker with Compose. Clone the repository and install its dependencies:
This is enough for code-only changes and unit tests. Start Postgres when you need the full stack or integration tests:
The development stack uses ports 5432, 8000, 8080, and 5000. If port 5432 is occupied, set AIRMUX_DEV_POSTGRES_PORT to a free port when starting Compose and export DATABASE_URL with that port in shells that run control-plane commands. For example:

Start the development environment

Migrate the fresh database, then load the development catalog:
Start each service in its own terminal. Control plane (http://127.0.0.1:8000):
Gateway (http://127.0.0.1:8080):
Webapp (http://127.0.0.1:5000):
Open 127.0.0.1:5000 and follow the setup steps. Then create a workspace and try Playground. Or set up and test the instance through the CLI:
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:
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. CI - Main runs the broader checks after merge. Address review feedback and merge after the required CI and security checks pass.

Release

Follow the release guide to prepare and publish a version.