Documentation

Environment Variables

Configure TraceLLM for local and production workflows.

Environment Variables

Version 1 Requirement

TraceLLM currently requires MongoDB for trace storage.

Required environment variables:

MONGO_URL
DB_NAME

Future versions may support additional storage options.

Tracey Tip

Ensure MONGO_URL and DB_NAME are set before starting the stack. Without them, traces are not persisted.

TraceLLM reads configuration from environment variables at startup. Variables can be set in a .env file (loaded via python-dotenv) or exported in the shell. The tracellm start command loads .envautomatically. Environment variable keys take precedence over .envfile values.

Backend Variables

These variables configure the Python backend (FastAPI server + SDK + CLI):

Variable	Required	Default	Description
MONGO_URL	Yes (for persistence)	None	MongoDB connection string (e.g. mongodb://localhost:27017 or Atlas SRV)
DB_NAME	Yes (for persistence)	None	MongoDB database name (e.g. tracellm)
OPENAI_API_KEY	For OpenAI integration	None	OpenAI API key for chat completions
TRACELLM_WS_HOST	No	127.0.0.1	WebSocket host for the CLI monitor
TRACELLM_WS_PORT	No	8000	WebSocket port for the CLI monitor
TRACELLM_PORT	No	8000	Port for the backend API server (used by start command)
TRACELLM_DASHBOARD_PORT	No	3000	Port for the frontend dashboard (used by start --dashboard)

Warning

Without MONGO_URL and DB_NAME, the API starts but traces are not persisted. The @tracedecorator logs a yellow "Trace persistence skipped" warning and the function still runs normally.

Frontend Variables

These variables configure the Next.js dashboard and are read at build time or runtime (client-side):

Variable	Required	Default	Description
NEXT_PUBLIC_API_BASE_URL	No	http://localhost:8000	Backend REST API base URL for fetch calls
NEXT_PUBLIC_WS_URL	No	Inferred from API_BASE_URL (http→ws)	WebSocket URL (e.g. ws://localhost:8000)

Info

Frontend variables use the NEXT_PUBLIC_ prefix for client-side access. The WebSocket URL is automatically derived by replacing http:// with ws:// in the API base URL, so NEXT_PUBLIC_WS_URL is only needed for custom deployments.

Loading Order

Variables are resolved in the following order (later sources override earlier ones):

Default values — hardcoded in code (e.g. port 8000)
.env file — loaded by python-dotenv in app/main.py and startup.py
Shell environment — export VAR=value or inline prefix

The FastAPI backend calls load_dotenv() in app/main.py on startup. The startup.py module also loads it for CLI usage. The frontend reads NEXT_PUBLIC_* variables from its own environment at build and runtime.

Example .env File

.envCopy

bash

# ── MongoDB ────────────────────────────────────────────────
MONGO_URL=mongodb://localhost:27017
DB_NAME=tracellm

# ── LLM Provider ───────────────────────────────────────────
OPENAI_API_KEY=sk-...

# ── TraceLLM Backend ───────────────────────────────────────
TRACELLM_PORT=8000
TRACELLM_WS_HOST=127.0.0.1
TRACELLM_WS_PORT=8000

# ── TraceLLM Dashboard ─────────────────────────────────────
TRACELLM_DASHBOARD_PORT=3000
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000

Tip

Create a .env file in the directory where you run tracellm start. The CLI loads it automatically. For the frontend, create a separate .env.local in the frontend/ directory.