Quickstart (local)

This quickstart runs the full Ax stack on your machine, then uses the ax CLI from a separate project directory.

Prerequisites

Docker Desktop, OrbStack, Colima, or Docker Engine with the Compose plugin.
uv installed on the machine where you run the CLI.
A local uv Python project to deploy.

If docker compose fails, start your Docker runtime first.

1. Start the platform

From the Ax repository root:

docker compose -f infra/docker-compose.yml up --build

With the default local configuration, the platform uses:

PLATFORM_BASE_DOMAIN=localhost
RUNNER_TOKEN=local-dev-token
Runner API at http://localhost

2. Install the CLI with `uv`

For normal local use, install the editable CLI as a global uv tool:

cd /path/to/ax
uv tool install -e ./cli

If you are changing the CLI itself, run it from the cli/ virtual environment instead:

cd /path/to/ax/cli
uv sync
uv run ax --help

From any directory:

ax login localhost --token local-dev-token

The host argument must match PLATFORM_BASE_DOMAIN. For local Compose, that value is localhost, so the CLI uses http://localhost.

4. Deploy a project

Move to the uv Python project you want to deploy:

cd /path/to/myapi
ax init
ax deploy

ax init writes the initial app metadata. ax deploy sends the project to the runner, where it is built and run as a container.

5. Operate the app

Use the same CLI for process state, lifecycle, and logs:

ax ps
ax start myapi
ax stop myapi
ax restart myapi
ax logs myapi --tail 300
ax rm myapi

Replace myapi with the app name from your ax.toml.

Local URL rules

localhost and *.localhost use HTTP.
Raw public IPs use HTTP.
Real hostnames use HTTPS.

For production, generate a token with ax generate, use that token on the server, then login with the same PLATFORM_BASE_DOMAIN. See Production & bootstrap.