Skip to main content

​
Ports

Phoenix is an all-in-one solution that has a tracing UI as well as a trace collector over both HTTP and gRPC. By default, the container exposes the following ports: If the above ports need to be modified, consult the section below.

​
Environment Variables

Phoenix uses environment variables to control how data is sent, received, and stored. Here is the comprehensive list:

​
Server Configuration

The following environment variables will control how your phoenix server runs.
  • PHOENIX_PORT: The port to run the phoenix web server. Defaults to 6006.
  • PHOENIX_GRPC_PORT: The port to run the gRPC OTLP trace collector. Defaults to 4317.
  • PHOENIX_HOST: The bind address for the Phoenix HTTP, gRPC, and Prometheus listeners. Defaults to 127.0.0.1 (:: in the Docker image and Helm chart). When PHOENIX_ENABLE_AUTH is unset, non-loopback addresses enable authentication automatically.
  • PHOENIX_HOST_ROOT_PATH: The root path prefix for your application. If provided, allows Phoenix to run behind a reverse proxy at the specified subpath. See an example here.
  • PHOENIX_WORKING_DIR: The directory in which to save, load, and export data. This directory must be accessible by both the Phoenix server and the notebook environment. Defaults to ~/.phoenix/
  • PHOENIX_ALLOW_EXTERNAL_RESOURCES: Controls whether Phoenix makes public-internet requests of its own, such as loading Google Fonts, sending telemetry, or downloading the WebAssembly sandbox runtime. Defaults to true. Set to false in air-gapped environments. Services you configure yourself, such as LLM providers and hosted sandboxes, aren’t affected. See Air-Gapped Deployments for the full list. Available since version 11.15.0.
  • PHOENIX_DISABLE_MODEL_COST_AUTO_UPDATE: Whether to turn off automatic updates of the built-in model prices. By default, Phoenix fetches the latest prices from GitHub shortly after startup and then about once a day, so new models get costs without an upgrade. Set to true so that built-in prices change only when you upgrade Phoenix; upgrading still updates them. Defaults to false. See Keeping built-in prices current.
  • PHOENIX_SQL_DATABASE_URL: The SQL database URL to use when logging traces and evals. if you plan on using SQLite, it’s advised to use a persistent volume and simply point the PHOENIX_WORKING_DIR to that volume. If URL is not specified, by default Phoenix starts with a file-based SQLite database in a temporary folder, the location of which will be shown at startup. Phoenix also supports PostgresSQL as shown below:
    • PostgreSQL, e.g. postgresql://@host/dbname?user=user&password=password or postgresql://user:password@host/dbname
    • SQLite, e.g. sqlite:///path/to/database.db
  • PHOENIX_SQL_DATABASE_READ_REPLICA_URL: Optional PostgreSQL read replica URL used for read-only queries. Writes continue to use your primary database connection. This setting is ignored for SQLite deployments. Example: postgresql://user:password@replica-host:5432/phoenix. Available since version 14.0.0.
  • PHOENIX_POSTGRES_HOST: As an alternative to setting PHOENIX_SQL_DATABASE_URL, you can set the following environment variables to connect to a PostgreSQL database:
    • PHOENIX_POSTGRES_HOST
    • PHOENIX_POSTGRES_PORT
    • PHOENIX_POSTGRES_USER
    • PHOENIX_POSTGRES_PASSWORD
    • PHOENIX_POSTGRES_DB
  • PHOENIX_POSTGRES_PORT: Used with PHOENIX_POSTGRES_HOST to specify the port to use for the PostgreSQL database.
  • PHOENIX_POSTGRES_USER: Used with PHOENIX_POSTGRES_HOST to specify the user to use for the PostgreSQL database.
  • PHOENIX_POSTGRES_PASSWORD: Used with PHOENIX_POSTGRES_HOST to specify the password to use for the PostgreSQL database.
  • PHOENIX_POSTGRES_DB: Used with PHOENIX_POSTGRES_HOST to specify the database to use for the PostgreSQL database.
  • PHOENIX_SQL_DATABASE_SCHEMA: An optional string specifying the PostgreSQL schema for the database tables. Similar to folders, schemas help organize tables outside the default public schema. If the specified schema does not exist, it will be created. This option is ignored when using SQLite.
  • PHOENIX_DEFAULT_RETENTION_POLICY_DAYS: Sets the default retention policy for traces in days. Defaults to 0 (infinite retention). When set to a positive value, traces older than this many days will be automatically removed from the database according to the configured cleanup schedule. This setting affects the default retention policy that applies to all projects unless overridden on a per-project basis through the Phoenix UI. See the data retention documentation for more details.
  • PHOENIX_ENABLE_PROMETHEUS: Whether to enable Prometheus metrics at port 9090. Defaults to false.
  • PHOENIX_SERVER_INSTRUMENTATION_OTLP_TRACE_COLLECTOR_HTTP_ENDPOINT: Specifies an HTTP endpoint for the OTLP trace collector. Specifying this variable enables the OpenTelemetry tracer and exporter for the Phoenix server.
  • PHOENIX_SERVER_INSTRUMENTATION_OTLP_TRACE_COLLECTOR_GRPC_ENDPOINT: Specifies an gRPC endpoint for the OTLP trace collector. Specifying this variable enables the OpenTelemetry tracer and exporter for the Phoenix server.
  • PHOENIX_SERVER_INSTRUMENTATION_OTLP_LOG_COLLECTOR_HTTP_ENDPOINT: Specifies an HTTP endpoint for the OTLP log collector. Specifying this variable exports the Phoenix server’s logs over OpenTelemetry, correlated with its traces.
  • PHOENIX_SERVER_INSTRUMENTATION_OTLP_LOG_COLLECTOR_GRPC_ENDPOINT: Specifies a gRPC endpoint for the OTLP log collector. Specifying this variable exports the Phoenix server’s logs over OpenTelemetry, correlated with its traces. Prefix the endpoint with http:// for a plaintext collector; without a scheme the exporter connects over TLS.
  • PHOENIX_CSRF_TRUSTED_ORIGINS: A comma-separated list of origins allowed to bypass Cross-Site Request Forgery (CSRF) protection. This setting is recommended when configuring OAuth2 clients or sending password reset emails. If this variable is left unspecified or contains no origins, CSRF protection will not be enabled. In such cases, when a request includes origin or referer headers, those values will not be validated.
  • PHOENIX_DEFAULT_ADMIN_INITIAL_PASSWORD: Sets the initial password for the built-in admin user (email admin@localhost) when that account is created on first startup or while it still holds the unchanged default password admin. Defaults to admin. Changing this after the default admin password has already been customized has no effect—update the password via the UI or an admin reset instead.
  • PHOENIX_ENABLE_STRONG_PASSWORD_POLICY: Enables a stronger password policy. When set to True, passwords must meet the following requirements: at least 12 characters, at least one uppercase letter, at least one lowercase letter, at least one number, and at least one special character. Defaults to False (minimum 4 characters). Available since version 13.5.0.
  • PHOENIX_TELEMETRY_ENABLED: Toggle for telemetry (enabled by default). Set to false if you want to disable all analytics tracking. Only basic web analytics are collected (e.g., page views, UI interactions). No trace data or sensitive information is ever collected.
  • PHOENIX_ALLOWED_PROVIDERS: A comma-separated, case-insensitive list of model provider names to display in the playground UI. When unset, all providers are shown. Set to NONE to hide all providers. Unrecognized provider names will cause a startup error. Supported values: OPENAI, ANTHROPIC, AZURE_OPENAI, GOOGLE, DEEPSEEK, XAI, OLLAMA, AWS, CEREBRAS, FIREWORKS, GROQ, MOONSHOT, MINIMAX, PERPLEXITY, TOGETHER, ZAI, META. Example: PHOENIX_ALLOWED_PROVIDERS=OPENAI,ANTHROPIC. Available since version 13.13.0.
  • PHOENIX_ENABLE_MCP_SERVER: Whether to mount the built-in remote MCP server (currently in beta) at /mcp. Defaults to true. Set to false to remove the endpoint entirely.
  • PHOENIX_ENABLE_MCP_CODE_MODE: Whether the built-in MCP server presents its code-mode tool surface, including an execute tool that runs agent-written Python in a sandboxed interpreter. Defaults to true. Set to false to disable code execution and expose plain, group-gated tools instead. Has no effect unless the MCP server is enabled. See Remote MCP Server for details.
  • PHOENIX_SKILLS_PATHS: Comma-separated directories of your own Agent Skills, loaded at startup and served alongside the built-in skills by PXI and the remote MCP server. For example: /opt/skills/team-analysis,/srv/agents/skills. Paths are on the Phoenix server. Relative paths resolve against the directory the server was started from, not PHOENIX_WORKING_DIR, so use absolute paths. See Add your own skills.
  • PHOENIX_ENABLE_OAUTH2_AUTHORIZATION_SERVER: Whether Phoenix serves its built-in OAuth2 authorization server, which lets MCP clients and the Phoenix CLI log in interactively via the browser. Defaults to true. Has no effect unless authentication is enabled. See OAuth2 Authorization Server for the full set of PHOENIX_OAUTH2_* tuning variables (grant expiry, dynamic client registration, redirect host allowlists, and rate limits).
  • PHOENIX_ALLOWED_SANDBOX_PROVIDERS: A comma-separated, case-insensitive list of code-execution sandbox providers that Phoenix is permitted to use. When unset, all providers are allowed. Set to NONE to disable every sandbox provider. Unrecognized provider names will cause a startup error. Supported values: WASM, DENO, MONTY, E2B, DAYTONA, VERCEL, MODAL, DOCKER. Example: PHOENIX_ALLOWED_SANDBOX_PROVIDERS=WASM,DENO. See Sandbox Backends for details.

​
Logging

  • PHOENIX_LOG_SQL: Whether to log all SQL statements to stdout. Useful for debugging database queries. Defaults to false. Available since version 13.4.0.

​
Client Connection Settings

These variables are read by your application, the SDKs, and the px CLI — not by the Phoenix server — to find and authenticate to your deployment. Phoenix’s SDKs, the px CLI, and MCP read their connection settings from environment variables. Two endpoint variables exist — one per concern, usually holding the same URL: Any Phoenix instance that isn’t running on the same machine as your app — a container, a Kubernetes deployment, or a managed host — is reached the same way: point PHOENIX_COLLECTOR_ENDPOINT at its hostname, and supply an API key if it has authentication enabled. That one variable covers tracing, the clients, and the px CLI.
If you set only one, set PHOENIX_COLLECTOR_ENDPOINT. It configures tracing, and the clients and the px CLI use it for API access too — so one value covers everything. PHOENIX_ENDPOINT is the canonical setting for those client surfaces, and it wins when both are set, but you rarely need it on its own. The fallback does not run both ways in every SDK. API access falls back to PHOENIX_COLLECTOR_ENDPOINT everywhere, but Python trace export does not yet read PHOENIX_ENDPOINT, so setting only PHOENIX_ENDPOINT can leave Python trace export pointed at http://localhost:6006. Set PHOENIX_ENDPOINT as well only when trace ingest and API access live at different URLs. PHOENIX_HOST is not a client setting — on the Phoenix server it is the bind host (e.g. 0.0.0.0, paired with PHOENIX_PORT). Some JS tools still accept it as a last-resort legacy fallback for the base URL, but new configuration should use the variables above.
Keep PHOENIX_ENDPOINT a base URL. The px CLI and the API clients append their own request paths to it.PHOENIX_COLLECTOR_ENDPOINT takes the shape the exporter reading it needs. register() derives the OTLP target from a base URL — the TypeScript SDK appends /v1/traces (OTLP/HTTP), while the Python SDK infers the transport, using OTLP/gRPC on port 4317 for self-hosted servers unless you pass protocol="http/protobuf"; a gRPC endpoint is just host:port.Exporters that POST to exactly the URL they are given — @mastra/arize’s ArizeExporter, a bare OTLPTraceExporter — need the full OTLP/HTTP URL. Set PHOENIX_COLLECTOR_ENDPOINT to the /v1/traces-suffixed form, or build that URL in code where the exporter is constructed, the way the Mastra examples do (`${PHOENIX_COLLECTOR_ENDPOINT}/v1/traces`). The px CLI and the API clients strip the suffix when inferring their base URL from it.With Python’s register(), pair a suffixed value with protocol="http/protobuf". Left to infer, the Python SDK rewrites the port to the gRPC port 4317 and keeps the /v1/traces path, and no spans arrive.

​
Choosing a project

PHOENIX_PROJECT selects the project that project-scoped operations write to and read from. PHOENIX_PROJECT_NAME is a supported alias for the same setting. When both are set, PHOENIX_PROJECT wins and Phoenix logs a one-time conflict warning. If neither is set, the project defaults to "default".

​
The .env.phoenix file

Instead of exporting variables in every shell, you can drop PHOENIX_-prefixed settings into a .env.phoenix file. The Phoenix SDKs and CLI auto-discover it: starting from the current working directory they walk up toward the filesystem root and load the first .env.phoenix they find (dotenv format).
This is the same file px setup writes: it records both endpoint variables (same value — one server) so trace export and API access are each explicit. A few rules worth knowing:
  • The process environment always wins. A value already set in the environment is never overridden by the file. Watch for endpoint variables exported globally — a PHOENIX_ENDPOINT in your shell profile, or in ~/.claude/settings.json from Claude Code tracing, applies in every directory and will shadow a project’s .env.phoenix. If px or a client is reaching the wrong Phoenix, check echo $PHOENIX_ENDPOINT first. Scope such variables to the session or project that needs them.
  • The filename is .env.phoenix, not .env.
  • Add it to your ignore rules before storing credentials in it — the Phoenix repository already git-ignores .env.phoenix.
  • Opt out by setting PHOENIX_DISCOVER_CONFIG=false (also accepts 0, no, off), which disables file discovery entirely.