Great question. Short answer: because every Prefect client (CLI, workers, and your flows) must know exactly which API to talk to, and there’s no reliable way to auto-detect that across different environments. A bit more detail (Prefect 3.x): - The API URL tells Prefect where to read/write deployments, create flow runs, report state, fetch work from work pools, etc. If it’s wrong, things won’t connect. - The default is local development:

<http://127.0.0.1:4200/api>

. That’s fine on your laptop while running

prefect server start

, but it’s wrong for Cloud, remote/self-hosted servers, containers, Kubernetes, or CI runners—where “localhost” is not your API. - Profiles give you safe, explicit, switchable configs per environment (dev/stage/prod). This avoids surprises from ambient environment variables and makes CLI/worker behavior reproducible. Typical scenarios: - Prefect Cloud:

prefect cloud login

creates/uses a profile and sets both

PREFECT_API_URL

and

PREFECT_API_KEY

for your workspace automatically. After that, all CLI and workers started under that profile connect to Cloud. - Self-hosted server (remote): you must set

PREFECT_API_URL

to the externally reachable API endpoint (e.g., behind your load balancer). Containers/K8s/CI must have this set in their environment or profile since

localhost

won’t work there. - Multiple environments: keep one profile per environment and switch with

prefect profile use <name>

to ensure every command/worker points to the right API. What happens if you don’t set it? - Prefect will try the local default. In non-local environments, you’ll see connection errors (e.g., connection refused to 127.0.0.1:4200) or authentication issues if you meant to use Cloud. How to set it explicitly - With a profile:

prefect profile create prod
  prefect profile use prod
  prefect config set PREFECT_API_URL=<https://prefect.mycompany.com/api>

Verify:

prefect config view

- As an environment variable (useful in containers/CI):

export PREFECT_API_URL=<https://prefect.mycompany.com/api>

- For Cloud (sets API URL and key for you):

prefect cloud login -k YOUR_KEY -w account/workspace

Docs you may find helpful: - Settings and Profiles: Settings and profiles - Managing settings (env vars, prefect.toml, profiles): Manage settings - Local/self-hosted server (CLI): Server CLI If you can share whether you’re using Cloud or a self-hosted server (and where your workers run), I can suggest the exact configuration approach for your setup.