> ## 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

<Steps>
  <Step title="Clone the repository">
    ```bash theme={"dark"}
    git clone https://github.com/tracectrl/tracectrl.git
    cd tracectrl
    ```
  </Step>

  <Step title="Choose your setup method">
    <Tabs>
      <Tab title="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>

      <Tab title="Manual Setup">
        ```bash theme={"dark"}
        cp .env.example .env
        docker compose up -d
        ```
      </Tab>

      <Tab title="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).
      </Tab>
    </Tabs>
  </Step>

  <Step title="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
    ```
  </Step>
</Steps>

## 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

<Steps>
  <Step title="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
    ```
  </Step>

  <Step title="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.
    </Warning>

    <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.
    </Note>
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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`.
</Note>