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.

Phoenix Cloud

Connect to a pre-configured, managed Phoenix instance

As a Container

Self-host your own Phoenix

In a Notebook

Run Phoenix in the notebook as you run experiments

From the Terminal

Run Phoenix via the CLI on your local machine

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

Phoenix Cloud

Phoenix Cloud provides free-to-use Phoenix instances that are preconfigured for you with 10GBs of storage space. Phoenix Cloud instances are a great starting point, however if you need more storage or more control over your instance, self-hosting options could be a better fit. If you’re using Phoenix Cloud, be sure to set the proper environment variables to connect to your instance:

import os

# Add Phoenix API Key for tracing
os.environ["PHOENIX_API_KEY"] = "ADD YOUR PHOENIX API KEY"
os.environ["PHOENIX_COLLECTOR_ENDPOINT"] = "ADD YOUR PHOENIX HOSTNAME"

# If you created your Phoenix Cloud instance before June 24th, 2025,
# you also need to set the API key as a header
os.environ["PHOENIX_CLIENT_HEADERS"] = f"api_key={os.getenv('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. Three of them are easy to confuse, so it’s worth being precise about what each one is for:

Variable	What it is	When to set it
`PHOENIX_COLLECTOR_ENDPOINT`	The base URL of the Phoenix server that receives your traces (the OTel collector). Set the base URL only — e.g. `https://app.phoenix.arize.com` or `http://localhost:6006` — not a full `/v1/traces` path.	Whenever your app and the Phoenix server are not on the same machine, or you’re using Phoenix Cloud. This is the variable the tracing SDKs (`register()`) use.
`PHOENIX_API_KEY`	The credential used to authenticate to a Phoenix instance that has auth enabled (Phoenix Cloud, or a self-hosted instance with authentication turned on).	When connecting to Phoenix Cloud or any authenticated deployment.
`PHOENIX_CLIENT_HEADERS`	Extra headers (JSON) sent with every request. Older Phoenix Cloud instances (created before June 24th, 2025) expect the API key here as `api_key=...`.	Only when a deployment requires custom headers, or for legacy Cloud instances.

Point PHOENIX_COLLECTOR_ENDPOINT at the server’s base URL. Setting it (or the legacy PHOENIX_HOST) to a full endpoint path such as .../v1/traces will misconfigure the exporter and your traces will not 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
PHOENIX_API_KEY=your-api-key
PHOENIX_PROJECT=my-app

A few rules worth knowing:

The process environment always wins. A value already set in the environment is never overridden by the file.
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

Phoenix Cloud

As a Container

In a Notebook

From the Terminal

Phoenix Cloud

Container

Notebooks

Terminal

Configuration & environment variables

Choosing a project

Credential file discovery (`.env.phoenix`)

Phoenix Cloud

As a Container

In a Notebook

From the Terminal

​Phoenix Cloud

​Container

​Notebooks

​Terminal

​Configuration & environment variables

​Choosing a project

​Credential file discovery (.env.phoenix)

Phoenix Cloud

Container

Notebooks

Terminal

Configuration & environment variables

Choosing a project

Credential file discovery (`.env.phoenix`)