Documentation

tracellm start

Start the local TraceLLM runtime.

Overview

The tracellm start command boots the entire TraceLLM observability stack: the FastAPI backend server, WebSocket endpoint, and — optionally — the frontend dashboard. It is the standard way to launch a local development environment.

Syntax

terminalCopy

bash

tracellm start [OPTIONS]

Option	Type	Default	Description
--port, -p	int	8000	Port for the API server
--dashboard, -d	flag	false	Open the dashboard in your browser
--dashboard-port	int	3000	Port for the frontend dashboard

What Happens Internally

Loads environment variables from a .env file using python-dotenv.
Initializes SQLite database — creates ~/.tracellm/traces.db if it does not exist. If creation fails, logs a yellow warning and continues — the API will start without persistence.
Starts the FastAPI server via a subprocess.Popen running uvicorn app.main:app on the specified port with live reload enabled.
Performs a health check by polling http://127.0.0.1:<port>/ with a 15-second timeout. The check retries every 500ms.
Opens the dashboard (if --dashboard is set) in the default browser using webbrowser.open.
Renders a status table showing API Server, SQLite, Dashboard, and WebSocket status.
Blocks on the API process until Ctrl+C is pressed, then terminates the uvicorn process gracefully.

Example Output

Terminal outputCopy

text

  ╭─── TraceLLM ───────────────────────────────────────────────╮
  │                                                          │
  │   ████████╗██████╗  █████╗  ██████╗███████╗             │
  │   ╚══██╔══╝██╔══██╗██╔══██╗██╔════╝██╔════╝             │
  │      ██║   ██████╔╝███████║██║     █████╗               │
  │      ██║   ██╔══██╗██╔══██║██║     ██╔══╝               │
  │      ██║   ██║  ██║██║  ██║╚██████╗███████╗             │
  │      ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝╚══════╝             │
  │                                                          │
  │   LLM Observability Platform                             │
  ╰──────────────────────────────────────────────────────────╯

  TraceLLM starting...

  ✓ SQLite connected
  ✓ API ready
  ✓ WebSocket ready

  ╭── TraceLLM Stack ────────────────────────────────────────╮
  │                                                          │
  │  API Server   ● http://127.0.0.1:8000                    │
  │  SQLite      ● Connected                                │
  │  Dashboard    ● http://localhost:3000                     │
  │  WebSocket    ws://127.0.0.1:8000/ws                     │
  │                                                          │
  ╰──────────────────────────────────────────────────────────╯

Environment Variables

Variable	Required	Description
None needed	No	SQLite auto-creates ~/.tracellm/traces.db on first run

Info

No environment variables are needed for storage. SQLite auto-creates the database file at ~/.tracellm/traces.db on first run.

Common Errors

Error	Cause	Fix
Port already in use	Another process is using the port	Use --port to specify a different port
Database file not created	~/.tracellm/ directory is not writable	Check directory permissions or create it manually: mkdir -p ~/.tracellm
API failed to start	Dependency issue or port conflict	Check the uvicorn logs for the exact error

Troubleshooting

Info

If the health check times out, ensure no firewall is blocking the port and that all dependencies are installed. Run pip install tracellm[all] to ensure all extras are available.