> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracectrl.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get TraceCtrl running end-to-end in 5 minutes

## Prerequisites

* **Docker** and **Docker Compose** v2
* **Python 3.10+** for the SDK in your agent
* **Node.js 20+** only if developing the dashboard

## Start the Platform

**1. Clone the repository**

```bash theme={"dark"}
git clone https://github.com/tracectrl/tracectrl.git
cd tracectrl
```

**2. Choose your setup method**

> [tab] CLI Wizard (Recommended)
>
> The CLI wizard walks you through configuration, writes your `.env` file, and launches the stack.
>
> ```bash theme={"dark"}
> pip install tracectrl
> tracectrl setup
> ```
>
> Or from source:
>
> ```bash theme={"dark"}
> pip install textual rich
> python setup/tui.py
> ```

> [tab] Manual Setup
>
> ```bash theme={"dark"}
> cp .env.example .env
> docker compose up -d
> ```

> [tab] Development Mode
>
> Hot reload for engine and UI:
>
> ```bash theme={"dark"}
> docker compose -f docker-compose.yml -f docker-compose.dev.yml up
> # Or use the Makefile shortcut
> make dev
> ```
>
> In dev mode, the engine auto-reloads on Python changes (port 8000) and the UI runs Vite dev server with HMR (port 5173).

**3. Verify the stack is running**

```bash theme={"dark"}
tracectrl doctor
```

You should see:

```
TraceCtrl Doctor

  [OK]   Engine API (http://localhost:8000/api/v1/health)
  [OK]   Dashboard UI (http://localhost:3000)
  [OK]   OTel Collector (HTTP) (http://localhost:4318/v1/traces)

All services are running.
```

Or manually:

```bash theme={"dark"}
docker compose ps
curl http://localhost:8000/api/v1/health
```

## Services & Ports

| Service | Port | Purpose |
| - | - | - |
| ClickHouse | `9000` (native), `8123` (HTTP) | Span storage, agent inventory, topology |
| OTel Collector | `4317` (gRPC), `4318` (HTTP) | Receives spans from SDK |
| TraceCtrl Engine | `8000` | REST API, pipeline scheduler |
| TraceCtrl Dashboard | `3000` | Topology graph, session explorer |

## Instrument Your Agent

**1. Install the SDK**

```bash theme={"dark"}
pip install tracectrl tracectrl-instrumentation-strands
```

For frameworks not yet on PyPI (LangChain, CrewAI, Google ADK), install from the repo:

```bash theme={"dark"}
pip install -e ./sdk/tracectrl-instrumentation-langchain
```

**2. Add a few lines before your agent code**

```python theme={"dark"}
import tracectrl

tracectrl.configure(
    service_name="my-agent-service",
    endpoint="http://localhost:4317",
)
tracectrl.tag_agent(name="my-agent", role="primary")

from tracectrl.instrumentation.strands import StrandsInstrumentor
StrandsInstrumentor().instrument()
```

> [!WARNING]
>
> These lines must come **before** any framework imports to ensure all modules are patched.

> [!NOTE]
>
> **Tag your agent.** `tracectrl.tag_agent(...)` attaches identity attributes
> (`tracectrl.agent.id`, `tracectrl.agent.name`, `tracectrl.agent.role`) to
> every span emitted from this process. Without it, the engine cannot group
> spans into the agent inventory or score per-agent risk. For multi-agent
> processes, use `tag_agents({...})` and call `tag_agent` inside each agent's
> execution scope.

**3. Run your agent normally**

```python theme={"dark"}
from strands import Agent
from strands.models import BedrockModel

agent = Agent(model=BedrockModel(model_id="anthropic.claude-3-5-sonnet"))
agent("Summarize my latest emails")
```

Every LLM call, tool invocation, and chain execution is now captured as OpenTelemetry spans enriched with TraceCtrl security attributes.

## Verify Data Flow

After running your agent, wait \~60 seconds for the pipeline to process, then:

### Check spans in ClickHouse

```bash theme={"dark"}
docker exec -it $(docker compose ps -q clickhouse) clickhouse-client \
  --query "SELECT
    SpanAttributes['tracectrl.agent.id'] AS agent_id,
    SpanAttributes['tracectrl.agent.name'] AS agent_name,
    SpanAttributes['tracectrl.tool.category'] AS tool_category,
    SpanName
  FROM tracectrl.otel_traces
  WHERE SpanAttributes['tracectrl.agent.id'] != ''
  LIMIT 20
  FORMAT Pretty"
```

### Check the agent inventory

```bash theme={"dark"}
docker exec -it $(docker compose ps -q clickhouse) clickhouse-client \
  --query "SELECT agent_id, name, framework, model, tools_observed, maturity
  FROM tracectrl.agent_inventory FINAL
  FORMAT Pretty"
```

### Query the Engine API

```bash theme={"dark"}
# Full topology graph
curl http://localhost:8000/api/v1/topology/graph | python -m json.tool

# Agent inventory
curl http://localhost:8000/api/v1/risk/agents | python -m json.tool
```

### View the Dashboard

Open [http://localhost:3000](http://localhost:3000) in your browser.

* **Topology** — Interactive graph showing agents, tools, and their connections
* **Sessions** — Trace explorer with full span trees and waterfall timelines

> [!NOTE]
>
> The pipeline runs every 60 seconds by default. If you don't see data immediately, wait for the next pipeline cycle and check `docker compose logs tracectrl-engine`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.