Choose the app's address

Audience: a coding agent working for a human. Every project's app answers on https://<name>.<apps domain>; previews on <name>-pr-<n>.<apps domain>. The name is the human's choice. Portuguese: pt-BR/app-address.md.

1. Before the first deploy, ask

get_app_address { "project_id": "<project_id>" }

confirmed is false until a person kept or chose the name. While it is, tell the human the url and ask whether to keep it or choose another one. The first deploy is the only moment nobody has the link yet, so a change costs nothing then. Never pick the name for them.

A name has 4 to 40 characters, a-z, 0-9 and single hyphens, starts and ends with a letter or a digit, and does not end in -pr-<number>. Platform names and look-alikes of brands or sign-in pages are refused.

check_app_address { "label": "painel-vendas", "project_id": "<project_id>" }

available, or reason (taken, reserved, brand, too_short, invalid, preview_shape, yours_retired) with suggestions that are free now. It never says who has a name.

2. Deploy with it

cortex deploy --address painel-vendas --json

The name is set before anything is queued: a refused name deploys nothing. Without --address, a person at a terminal is asked (Enter keeps the name); without a terminal the companion never asks, and the JSON carries address_question until someone answers. Keeping the current name also confirms it: set_app_address with the same label, or cortex address set <current name>.

3. Changing it later

set_app_address { "project_id": "<project_id>", "label": "novo-nome" }
cortex address set novo-nome

No redeploy. Once a name went live, changing it needs confirm set to the current hostname, typed by the human (cortex address set asks for it at a terminal). The answer's next_step says what happens to the old address: it either redirects to the new one for 30 days or stops answering, depending on the platform, and custom domains that redirect to the old address are listed to repoint.

• A name that went live stays with your organization for good: no other organization can take it, and set_app_address takes it back for any of your projects.
• At most 5 changes per project in 24 hours and 5 earlier names counting per project (each counts for 90 days). changes_left_24h and retired in get_app_address say where you are.
• Ending an earlier name's redirect early (release_app_address) is done in the console by an owner or admin. With a token the answer is auth.forbidden with the console link: give the link to the human.

Verify: get_app_address shows confirmed: true and the chosen url, and https://<name>.<apps domain>/healthz answers 200 after the deploy.