Implementation:Arize ai Phoenix Client Config

Knowledge Sources	Arize_ai_Phoenix
Domains	AI_Observability, Client_SDK, Configuration
Last Updated	2026-02-14 05:30 GMT

Overview

Configuration utilities for reading Phoenix client settings from environment variables with validation, defaults, and URL construction.

Description

The Client Config module provides a set of functions for resolving Phoenix client configuration from environment variables. It serves as the single source of truth for how the Phoenix client discovers and connects to a Phoenix server instance.

Key functions include:

• get_env_phoenix_api_key() -- Reads the PHOENIX_API_KEY environment variable for authentication.
• get_env_port() -- Reads PHOENIX_PORT and validates it is numeric, falling back to the default port constant.
• get_env_host() -- Reads PHOENIX_HOST, falling back to the default host constant.
• get_env_host_root_path() -- Reads PHOENIX_HOST_ROOT_PATH for reverse proxy deployments. Validates that the path starts with / and does not end with /.
• get_env_client_headers() -- Reads PHOENIX_CLIENT_HEADERS (parsed from a W3C-compatible header format) and automatically injects an Authorization: Bearer header if an API key is set but no authorization header is present.
• get_env_collector_endpoint() -- Reads PHOENIX_COLLECTOR_ENDPOINT or falls back to OTEL_EXPORTER_OTLP_ENDPOINT for OpenTelemetry compatibility.
• get_base_url() -- Constructs the full base URL as an httpx.URL. Prefers the collector endpoint if set; otherwise assembles the URL from host and port. Translates 0.0.0.0 to 127.0.0.1 for local development.
• get_env_project_name() -- Reads PHOENIX_PROJECT_NAME, defaulting to "default".

All environment variable reads go through a private getenv() wrapper that strips leading and trailing whitespace from values to handle inadvertent whitespace in shell configurations.

Usage

Use these functions when initializing the Phoenix client or any component that needs to discover the Phoenix server address and authentication credentials. They are typically called during client construction and are designed to work in both local development and production deployments behind reverse proxies.

Code Reference

Source Location

• Repository: Arize_ai_Phoenix
• File: packages/phoenix-client/src/phoenix/client/utils/config.py

Signature

def get_env_phoenix_api_key() -> Optional[str]: ...
def get_env_port() -> int: ...
def get_env_host() -> str: ...
def get_env_host_root_path() -> str: ...
def get_env_client_headers() -> dict[str, str]: ...
def get_env_collector_endpoint() -> Optional[str]: ...
def get_base_url() -> httpx.URL: ...
def get_env_project_name() -> str: ...

Import

from phoenix.client.utils.config import (
    get_env_phoenix_api_key,
    get_env_port,
    get_env_host,
    get_env_host_root_path,
    get_env_client_headers,
    get_env_collector_endpoint,
    get_base_url,
    get_env_project_name,
)

I/O Contract

Environment Variables

Variable	Function	Default	Validation
PHOENIX_API_KEY	get_env_phoenix_api_key()	None	None
PHOENIX_PORT	get_env_port()	Built-in PORT constant	Must be numeric; raises ValueError otherwise
PHOENIX_HOST	get_env_host()	Built-in HOST constant	None
PHOENIX_HOST_ROOT_PATH	get_env_host_root_path()	""	Must start with /; must not end with /
PHOENIX_CLIENT_HEADERS	get_env_client_headers()	{}	Parsed via W3C-compatible header parser
PHOENIX_COLLECTOR_ENDPOINT	get_env_collector_endpoint()	Falls back to OTEL_EXPORTER_OTLP_ENDPOINT	None
PHOENIX_PROJECT_NAME	get_env_project_name()	"default"	None

Return Values

Function	Return Type	Description
get_base_url()	httpx.URL	Fully constructed base URL for Phoenix server
get_env_client_headers()	dict[str, str]	Headers dict with auto-injected Bearer auth if API key is set
get_env_port()	int	Validated port number
get_env_host_root_path()	str	Root path prefix (empty string if not set)

Usage Examples

import os
from phoenix.client.utils.config import get_base_url, get_env_client_headers

# Set environment for a remote Phoenix deployment
os.environ["PHOENIX_COLLECTOR_ENDPOINT"] = "https://phoenix.example.com"
os.environ["PHOENIX_API_KEY"] = "my-secret-key"

base_url = get_base_url()
# httpx.URL("https://phoenix.example.com")

headers = get_env_client_headers()
# {"Authorization": "Bearer my-secret-key"}

# Local development with default settings
os.environ.pop("PHOENIX_COLLECTOR_ENDPOINT", None)
os.environ.pop("PHOENIX_API_KEY", None)

base_url = get_base_url()
# httpx.URL("http://127.0.0.1:6006")  (assuming default host/port constants)

Related Pages

• Principle:Arize_ai_Phoenix_Client_Initialization
• Arize_ai_Phoenix_Client_Executors -- Executors that rely on client configuration for server connectivity