Documentation

Installation

Supported installation paths and environment setup.

Requirements

Python 3.11+
MongoDB Atlas or Self-Hosted MongoDB

Version 1 Requirement

TraceLLM currently requires MongoDB for trace storage.

Required environment variables:

MONGO_URL
DB_NAME

Future versions may support additional storage options.

Prerequisites

Python 3.10 or later
MongoDB 6.0 or later (local or remote)
pip (Python package manager, included with Python 3.10+)

Info

TraceLLM works with any MongoDB-compatible service, including MongoDB Atlas and local Docker instances.

Install TraceLLM

The recommended install path is via pip. All runtime dependencies — including the CLI, SDK, and WebSocket client — are bundled in a single package.

terminalCopy

bash

pip install tracellm

SetupCopy

bash

# Configuration
MONGO_URL=mongodb://localhost:27017
DB_NAME=tracellm

# Start
tracellm start

Tracey Guide

After installing, set your MONGO_URL and DB_NAME environment variables, then run tracellm start to launch the stack.

To install with optional extras:

terminalCopy

bash

pip install "tracellm[openai]"     # OpenAI integration
pip install "tracellm[groq]"       # Groq integration
pip install "tracellm[langchain]"   # LangChain integration
pip install "tracellm[all]"         # All integrations

Verify Installation

Confirm TraceLLM installed correctly:

terminalCopy

bash

tracellm --version
tracellm --help

You should see the version number and a list of available commands. To verify the full stack starts correctly:

terminalCopy

bash

tracellm start --check

Tip

start --check runs a health probe on each service without keeping the process running.

Troubleshooting

Common installation issues and their fixes:

Issue	Solution
pip install fails	Upgrade pip: pip install --upgrade pip
MongoDB connection refused	Ensure MongoDB is running: mongod --dbpath /data/db
Port 3000 already in use	Set TRACELLM_PORT=3001 before starting
WebSocket won't connect	Check firewall rules for port 3200
Command not found after install	Verify your Python bin directory is in PATH
ImportError in SDK code	Ensure no other tracellm versions are installed: pip list \| grep tracellm