Environments

The Phoenix app can be run in various environments such as Colab and SageMaker notebooks, as well as be served via the terminal or a docker container.

From the Terminal

Run Phoenix via the CLI on your local machine

As a Container

Self-host your own Phoenix

In a Notebook

Run Phoenix in the notebook as you run experiments

If you are set up, see Quickstarts to start using Phoenix in your preferred environment.

Remote deployments

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.

import os

os.environ["PHOENIX_COLLECTOR_ENDPOINT"] = "https://your-phoenix.example.com"

# Only if the deployment has authentication enabled
os.environ["PHOENIX_API_KEY"] = "ADD YOUR PHOENIX API KEY"

Container

See Self-Hosting.

Notebooks

To start phoenix in a notebook environment, run:

import phoenix as px

session = px.launch_app()

This will start a local Phoenix server. You can initialize the phoenix server with various kinds of data (traces, inferences).

By default, Phoenix does not persist your data when run in a notebook.

Terminal

If you want to start a phoenix server to collect traces, you can also run phoenix directly from the command line:

phoenix serve

This will start the phoenix server on port 6006. If you are running your instrumented notebook or application on the same machine, traces should automatically be exported to http://127.0.0.1:6006 so no additional configuration is needed. However if the server is running remotely, you will have to modify the environment variable PHOENIX_COLLECTOR_ENDPOINT to point to that machine (e.g. http://<my-remote-machine>:<port>)

Configuration & environment variables

Phoenix reads its connection settings from environment variables. Two endpoint variables exist — one per concern, usually holding the same URL:

Variable	What it is	When to set it
`PHOENIX_COLLECTOR_ENDPOINT`	Where your traces are exported. Read by `register()` and the OTLP exporters it configures. Takes either a Phoenix base URL (`http://localhost:6006`) or a full OTLP trace endpoint (`http://localhost:6006/v1/traces`), depending on the exporter that reads it.	Whenever you are tracing to a Phoenix that isn’t at `http://localhost:6006`. Phoenix’s OTel SDKs take their export target from this variable.
`PHOENIX_ENDPOINT`	The base URL for everything except trace export — the API clients, the `px` CLI, and MCP. Always a base URL (e.g. `http://localhost:6006`), never a request path.	Whenever you use those against a Phoenix that isn’t at `http://localhost:6006`. Falls back to `PHOENIX_COLLECTOR_ENDPOINT`.
`PHOENIX_API_KEY`	The credential used to authenticate to a Phoenix instance that has authentication enabled.	When connecting to any authenticated deployment. A local `phoenix serve` needs none.
`PHOENIX_CLIENT_HEADERS`	Extra headers (JSON) sent with every request, e.g. `api_key=...`.	Only when a deployment requires custom headers.

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 both — to the same value in the usual case where one Phoenix serves both concerns, which is what px setup writes into .env.phoenix, or to different values when trace ingest and API access genuinely 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".

import os

os.environ["PHOENIX_PROJECT"] = "my-app"   # canonical
# PHOENIX_PROJECT_NAME is accepted as an alias for the same value

Credential file discovery (`.env.phoenix`)

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).

# .env.phoenix
PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006  # traces are exported here
PHOENIX_ENDPOINT=http://localhost:6006            # API requests go here
PHOENIX_API_KEY=your-api-key
PHOENIX_PROJECT=my-app

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.

Get Started

Tracing

Evaluation

Datasets & Experiments

Prompts

Settings

Concepts

Resources

From the Terminal

As a Container

In a Notebook

Remote deployments

Container

Notebooks

Terminal

Configuration & environment variables

Choosing a project

Credential file discovery (`.env.phoenix`)

From the Terminal

As a Container

In a Notebook

​Remote deployments

​Container

​Notebooks

​Terminal

​Configuration & environment variables

​Choosing a project

​Credential file discovery (.env.phoenix)

Remote deployments

Container

Notebooks

Terminal

Configuration & environment variables

Choosing a project

Credential file discovery (`.env.phoenix`)