Reverse Proxy Sub-Path Deployment#

Phoenix supports deployment behind a reverse proxy at a URL sub-path (e.g., https://example.com/phoenix). This requires coordinating three subsystems:

1. Uvicorn server — must be told the ASGI root_path so it strips the prefix from incoming requests.
2. Phoenix client (phoenix-client) — must append the sub-path to every derived API base URL.
3. Agent-generated links — must use root-relative redirect URLs so they work regardless of the proxy prefix.

The central environment variable is PHOENIX_HOST_ROOT_PATH. It must start with / and must not end with / (e.g., /phoenix is valid; phoenix, /phoenix/ are both invalid) 1.

Note: Setting only PHOENIX_HOST_ROOT_PATH is not enough for a complete deployment. PHOENIX_ROOT_URL must also be set to the full public URL (e.g., https://example.com/phoenix) so Phoenix can generate correct external links 2.

Environment Variables#

Both variables are defined in src/phoenix/config.py. The default for PHOENIX_HOST_ROOT_PATH is an empty string (no sub-path) 3.

get_env_host_root_path() validates the value and is shared between the server and client packages 1 4.

get_env_root_url() on the server side first checks for an explicit PHOENIX_ROOT_URL; if absent, it constructs the URL from PHOENIX_HOST, PHOENIX_PORT, and PHOENIX_HOST_ROOT_PATH using urljoin 5.

Server: Uvicorn Configuration#

src/phoenix/server/main.py reads get_env_host_root_path() at startup and passes it directly to Uvicorn's Config object 6 7:

host_root_path = get_env_host_root_path()
# ...
server_config = Config(app=app, host=host, port=port, root_path=host_root_path, ...)

This is the standard ASGI root_path mechanism — Starlette/Uvicorn uses it to strip the prefix from incoming request paths before routing them through the application.

The startup banner URL is also constructed with urljoin to include the root path 8:

display_root_path = urljoin(f"{http_scheme}://{display_host}:{port}", host_root_path)

Client: Base URL Construction#

The phoenix-client package builds a base URL in get_base_url(). Previously, this function omitted PHOENIX_HOST_ROOT_PATH, causing all client API calls to hit the origin root (e.g., /v1/traces) instead of the sub-path (e.g., /phoenix/v1/traces) when deployed behind a reverse proxy.

Two PRs address this:

• PR #13984 (fix(client): include PHOENIX_HOST_ROOT_PATH in default get_base_url()) — appends get_env_host_root_path() to the fallback host:port derived URL.
• PR #14054 (fix(client): include PHOENIX_HOST_ROOT_PATH in derived base_url) — extends the fix to also cover collector-endpoint derived URLs (using rstrip("/") to handle trailing-slash edge cases before joining).

Both fixes are backward-compatible: get_env_host_root_path() returns "" when PHOENIX_HOST_ROOT_PATH is unset 9. The client-side validation applies the same constraints as the server: value must start with /, must not end with / 10.

Agent-Generated Trace and Span Links#

The Phoenix debug-trace agent produces markdown links pointing at specific traces and spans. These links must work correctly regardless of the sub-path prefix.

Standardized format 11: the agent uses root-relative redirect URLs:

• Span link: /redirects/spans/<spanId>
• Trace link: /redirects/traces/<traceId>

Rules standardized in PR #13498 (fix(agent): guide debug-trace span/trace link formatting):

• Prefer span links over trace links when the issue is localized to a single span.
• Use OTel hex IDs from the spanId and traceId GraphQL fields — not the Relay id field.

These root-relative paths navigate through React Router for client-side routing. PR #13345 (fix(app): route PXI markdown links through router) fixed markdown link routing to go through the React Router rather than the browser, and was explicitly tested under PHOENIX_HOST_ROOT_PATH=/phoenix — ensuring sub-path deployments resolve links correctly.

Key Files and Entry Points#

Recent fixes (newest first):

• PR #14054 — client get_base_url() with collector endpoint derivation
• PR #13984 — client get_base_url() with host+port derivation
• PR #13498 — agent span/trace link format standardization
• PR #13345 — PXI markdown link routing through React Router