ax.toml reference

ax.toml tells Ax how to build, run, and route your app.

Create it with ax init, then edit it to match the app you want to deploy. The file should live at the root of the uv Python project you deploy with ax deploy.

Minimal web app

name = "myapi"
type = "web"
start = "uv run uvicorn myapi.app:app --host 0.0.0.0 --port $PORT"
port = 8000

[ingress]
# Choose one:
# mode = "platform-path"         # https://<platform-base-domain>/myapi/*
# path = "/myapi"
#
# mode = "platform-subdomain"    # https://myapi.<platform-base-domain>/*
# subdomain = "myapi"
#
# mode = "custom-domain"         # https://api.example.com/*
# domains = ["api.example.com"]

[env]
ENV = "prod"

Top-level fields

• name - stable app name used by ax deploy, ax ps, ax logs, ax restart, and app routing defaults.
• type - app kind. Use web for HTTP services.
• start - command Ax runs inside the app container.
• port - internal port your web process listens on.

For web apps, bind to 0.0.0.0 and use the same port as port. The example above uses $PORT so the command and manifest stay aligned.

Ingress modes

Pick one [ingress] mode.

Platform path

Route the app under the base domain:

[ingress]
mode = "platform-path"
path = "/myapi"

Result:

https://<platform-base-domain>/myapi/*

Use this when you want the fewest DNS records and a simple shared host for internal apps.

Platform subdomain

Route the app on a subdomain of the base domain:

[ingress]
mode = "platform-subdomain"
subdomain = "myapi"

Result:

https://myapi.<platform-base-domain>/*

Use this when each app should have a cleaner host and your DNS/TLS setup supports it.

Custom domain

Route the app on one or more explicit domains:

[ingress]
mode = "custom-domain"
domains = ["api.example.com"]

Result:

https://api.example.com/*

Use this when the app needs a public product or customer-facing domain.

Environment variables

Values under [env] are injected into the app container:

[env]
ENV = "prod"
LOG_LEVEL = "info"

Do not commit secrets unless your repository is private and your team has agreed that repo-managed secrets are acceptable. Prefer environment-specific handling for credentials and tokens.

Practical checks

Before deploying, check that:

• start works locally with uv run.
• The process listens on 0.0.0.0, not only 127.0.0.1.
• port matches the port your server actually uses.
• Exactly one ingress mode is configured.
• The app name is stable; changing it creates a different lifecycle target for CLI commands.

For the full narrative around DNS and TLS, see Production & bootstrap.