> ## Documentation Index
> Fetch the complete documentation index at: https://arizeai-433a7140-feat-new-brand-design-system.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
Run Phoenix via the CLI on your local machine
Self-host your own Phoenix
Run Phoenix in the notebook as you run experiments
If you are set up, see [Quickstarts](/docs/phoenix/get-started) 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](/docs/phoenix/self-hosting/features/authentication) enabled.
```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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](/docs/phoenix/self-hosting).
### Notebooks
To start phoenix in a notebook environment, run:
```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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:
```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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://:`)
## 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](/docs/phoenix/self-hosting/features/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"`.
```python theme={"theme":{"light":"github-light-default","dark":"github-dark-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).
```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
# .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](/docs/phoenix/integrations/coding-agents/claude-code), 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.