Duration: 1.5–2 hours | Level: Intermediate | Format: Hands-on lab
Using an AI assistant?
Paste the TraceCtrl agent instructions into Claude Code, Cursor, or Copilot to get contextual help throughout this workshop.
Part 1: Introduction to TraceCtrl
What is TraceCtrl?
TraceCtrl is a security observability platform for agentic AI. Our tagline captures the workflow:- See — Visualize your agent’s architecture, topology, and risk posture at a glance
- Trace — Trace every message, tool call, and model request through the full execution lifecycle
- Ctrl — Control and harden your agent’s configuration with automated scanning and remediation
Components
TraceCtrl has five components:| Component | What it does | Technology |
|---|---|---|
| CLI | tracectrl scan, fix, doctor, setup | Python (pip installable) |
| Scanner | 33 security/ops/perf/compliance checks for OpenClaw | Python |
| OTel Collector | Receives spans from agents via OTLP | OpenTelemetry Collector |
| Engine | Processes spans, builds topology, serves API | FastAPI + ClickHouse |
| Dashboard | Visualizes scans, traces, topology | React + Vite + Cytoscape.js |
Architecture
AGENT CODE
OTLP gRPC :4317
OPENCLAW
OTLP HTTP :4318
→
OTEL COLLECTOR
:4317 / :4318
→
CLICKHOUSE
native :9000
→
ENGINE API
:8000
→
DASHBOARD
:3000
tracectrl scan
POST findings → Engine
tracectrl fix
auto-remediates OpenClaw config
- Your agent (or OpenClaw) exports OpenTelemetry spans to the OTel Collector
- The Collector writes spans to ClickHouse (column-oriented database optimized for traces)
- The Engine runs a pipeline every 60 seconds — reads new spans, builds agent inventory, discovers topology edges
- The Dashboard queries the Engine API to render trace trees, topology graphs, and scan reports
- The CLI Scanner analyzes OpenClaw config files and uploads findings to the Engine
What the Scanner Checks
33 checks across four categories:| Category | Checks | Examples |
|---|---|---|
| Security (26) | Network, credentials, tools, sandbox, SSRF, auth | Gateway exposed? Plaintext API keys? Dangerous tools allowed? |
| Operational (2) | Model config, fallbacks | Primary model set? Fallback configured? |
| Performance (2) | Sub-agent limits | Timeouts configured? Concurrency bounded? |
| Compliance (3) | Retention, isolation, redaction | Session data purged? User contexts isolated? |
Part 2: Prerequisites
Install all of the following before the bootcamp. Each tool has platform-specific instructions and a verification step at the end.Required Software
Git
Git Downloads
Official Git downloads for all platforms.
- macOS
- Ubuntu / Debian
- Windows (WSL2)
- EC2 (Amazon Linux 2023)
git version 2.x.x
Python 3.10+
Python Downloads
Official Python downloads — choose 3.12 or later.
- macOS
- Ubuntu / Debian
- Windows (WSL2)
- EC2 (Amazon Linux 2023)
Python 3.10.x or higher
Node.js 22+
Node.js Downloads
Official Node.js downloads — choose the 22 LTS release.
- macOS
- Ubuntu / Debian
- Windows (WSL2)
- EC2 (Amazon Linux 2023)
v22.x.x and 10.x.x
Docker
Docker Desktop
Docker Desktop for macOS and Windows. Docker Engine for Linux and EC2.
- macOS
- Ubuntu / Debian
- Windows (WSL2)
- EC2 (Amazon Linux 2023)
Docker Desktop must be running (whale icon in menu bar) before any
docker command works. It needs ~4 GB of RAM.Docker version 27.x.x and Docker Compose version v2.x.x
OpenClaw
OpenClaw Documentation
Full installation guide and platform requirements.
- macOS
- Ubuntu / Debian
- Windows (WSL2)
- EC2 (Amazon Linux 2023)
openclaw x.x.x
Quick Verification
Paste this into your terminal to check all prerequisites at once:API Keys
You’ll need an API key for an LLM provider to power your OpenClaw agent. Pick one from the options below — Gemma via Google AI Studio is free and works well for the bootcamp.| Provider | Free Tier | Sign Up |
|---|---|---|
| Google AI Studio (Gemma 3 / Gemini) | Yes — free API key, no credit card | aistudio.google.com |
| Anthropic (Claude) | No — requires billing | console.anthropic.com |
| OpenAI (GPT-4o) | No — requires billing | platform.openai.com |
| Groq (Llama, Mixtral) | Yes — free tier available | console.groq.com |
Recommended for bootcamp: Get a free Google AI Studio key. Go to aistudio.google.com, sign in with a Google account, and click Get API key. No credit card required.
Part 3: OpenClaw Setup
What is OpenClaw?
OpenClaw is a self-hosted AI agent gateway. It connects LLMs to messaging channels (Telegram, WhatsApp, Discord, Slack, WebChat) and manages agent configuration, tool access, session state, and model routing — all from a single JSON config file.OpenClaw Documentation
Full reference: installation, configuration, plugins, channels, and tools.
Run the Setup Wizard
- Model provider — Select Anthropic and enter the API key
- Channel — Choose WebChat for the bootcamp (no external accounts needed)
- Identity — Name your agent (e.g., “Bootcamp Agent”)
API Key: Ask the facilitator for the Anthropic API key. It can also be found in the Notion document “LLM Providers (API Keys)”.
Understand the Configuration
After setup, your config lives at~/.openclaw/openclaw.json (or a custom path if you chose one during the wizard).
Not sure of your workspace path? Run this in your normal user shell (not sudo):
/home/yourname/.openclaw — and use that wherever the docs reference ~/.openclaw.
Here are the key sections:
| Section | What it controls |
|---|---|
agents.defaults.model | Which LLM to use (primary + fallbacks) |
channels | Messaging channels and their DM/group policies |
gateway | Network binding, authentication, TLS |
tools | Which tools the agent can access (full, coding, messaging, minimal) |
session | Conversation scope (main, per-peer, per-channel-peer) and retention |
logging | Log level (info, debug, trace) and sensitive data redaction |
diagnostics | OpenTelemetry export for runtime traces |
plugins | Which plugins are enabled (providers, channels, tools) |
OpenClaw Configuration Reference
Full configuration reference with all options.
Enable Diagnostics (OTEL Export)
For TraceCtrl to receive runtime traces from OpenClaw, enable the diagnostics-otel plugin. Edit~/.openclaw/openclaw.json and add these sections:
Test Your Agent
Open the OpenClaw Control UI at http://localhost:18789 and send a test message via WebChat. If you set up Telegram, you can message your bot there instead.Checkpoint: You can chat with your agent via WebChat or Telegram. OpenClaw is running with diagnostics enabled.
Part 4: TraceCtrl Setup
Clone and Install
⭐ Star TraceCtrl on GitHub
You just cloned it — if it looks useful, a star helps others find the project. Takes 2 seconds.
Start the Stack
| Container | Port | Purpose |
|---|---|---|
clickhouse | 8123, 9000 | Span storage (ClickHouse database) |
otel-collector | 4317, 4318 | Receives OpenTelemetry spans |
tracectrl-engine | 8000 | Intelligence Engine (API + pipeline) |
tracectrl-ui | 3000 | Dashboard (React web app) |
Open the Dashboard
Open http://localhost:3000 in your browser. You’ll see the TraceCtrl dashboard — currently empty. We’ll populate it in the next sections.Checkpoint:
tracectrl doctor shows all green. Dashboard loads at localhost:3000.Part 5: Static Scan & Risk Topology
Run the Scan
First, get your absolute workspace path — run this in your normal user shell (not as sudo):openclaw.json, runs 33 checks, and uploads results to the dashboard.
Terminal output shows a severity summary, findings table, compound risk signals, and topology stats:
CRITICAL 5
HIGH 14
MEDIUM 14
PASS 0
| Check ID | Severity | Finding |
|---|---|---|
| OC-NET-001 | CRITICAL | Gateway bind is non-loopback — exposed to network |
| OC-SEC-001 | CRITICAL | No auth on network-exposed gateway |
| OC-SEC-002 | CRITICAL | Dangerous flags active: browser.ssrfPolicy… |
| OC-TOOL-001 | CRITICAL | bash/exec tools enable arbitrary command execution |
| OC-TOOL-002 | CRITICAL | Wildcard tool permission — all tools permitted |
| OC-CRED-001 | HIGH | Plaintext keys found at: models.providers.vllm.apiKey |
| OC-SEC-004 | HIGH | sandbox.mode is “off” — no tool isolation |
| OC-SEC-005 | HIGH | Browser SSRF: dangerouslyAllowPrivateNetwork is true |
| OC-OPS-001 | HIGH | No primary model configured |
| … 24 more findings (33 checks total) | ||
Compound Risk Signals
[HIGH] COMPOUND-004 Plaintext credentials + public channel = credential exfiltration risk
Topology: 9 nodes · 8 edges
View in the Dashboard
Open http://localhost:3000/scan to see:- Severity cards — CRITICAL / HIGH / MEDIUM / PASS counts
- Architecture risk topology — your OpenClaw architecture with risk-colored nodes
- Category sections — findings grouped by Security, Operational, Performance, Compliance
Reading the Topology Graph
| Node Color | Type |
|---|---|
| Teal | Ingress channels (Telegram, WebChat) |
| Blue | Agents |
| Purple | LLM Providers (Anthropic, OpenAI) |
| Green | Tools |
| Orange | Extensions/Plugins |
Exploring Findings
Expand each category section to see individual findings. Click any finding to see:- What was found — the specific misconfiguration
- Why it matters — the security/operational rationale
- How to fix it — step-by-step remediation
Auto-Fix Critical Findings
| Finding | What the fix does |
|---|---|
OC-NET-001 Gateway exposed | Sets gateway.bind = "loopback" |
OC-TOOL-001 Dangerous tools | Removes bash, exec from allow lists |
OC-TOOL-002 Wildcard tools | Removes * from tools.allow |
OC-ING-001 Open DM policy | Sets dmPolicy = "pairing" |
OC-PERS-001 Cron enabled | Sets cron.enabled = false |
OC-LOG-002 Debug logging | Sets logging.level = "info" |
.bak backup, applies fixes, re-scans, and uploads results:
Manual Fixes
Some findings require manual remediation. Here are the most important ones:Plaintext API Keys (OC-CRED-001)
Problem: API keys stored directly inopenclaw.json.
Fix: Replace with environment variable references:
openclaw configure to reconfigure the provider with an env var.
Browser SSRF Policy (OC-SEC-002)
Problem:browser.ssrfPolicy.dangerouslyAllowPrivateNetwork is true by default — the agent’s browser can reach your internal network.
Fix: Add to openclaw.json:
Sandbox Not Enabled (OC-SEC-004)
Problem: Agent tools run directly on the host without isolation. Fix:Session Scope Shared (OC-COMP-002)
Problem: All users share the same conversation context. Fix:OpenClaw Security Guide
Full security configuration reference.
Re-scan After Manual Fixes
Checkpoint: 0 CRITICAL findings. Dashboard shows the updated scan report with risk topology.
Part 6: Strands Agent + Runtime Telemetry
What is Strands?
AWS Strands is an open-source SDK for building AI agents with tool use. TraceCtrl instruments Strands agents to capture every execution — agent runs, LLM calls, and tool invocations — as OpenTelemetry spans.Install the Strands Instrumentation
From the TraceCtrl repo root:Create a Strands Agent
Create a file calledmy_agent.py:
API Key: Set your credentials before running:Ask the facilitator for keys, or check the Notion document “LLM Providers (API Keys)”.
Run the Agent
View the Traces
Open http://localhost:3000/sessions. You’ll see a new trace forbootcamp-agent. Click the row to expand the trace tree:
- Agent span — the top-level agent execution
- LLM spans — each model call with input/output and token counts
- Tool spans — calculator tool with arguments and result
View the Topology
Open http://localhost:3000/topology. The runtime topology graph now shows:- Agent node (bootcamp-agent) → connected to the LLM provider (Anthropic/Bedrock)
- Agent node → connected to tool nodes (calculator)
Try More Complex Scenarios
Multi-tool Agent
Multiple Runs
Run the agent several times to build up session history:What Gets Captured
| Span Type | Key Attributes |
|---|---|
| Agent | agent.name, openinference.span.kind=AGENT |
| LLM | llm.model_name, input.value, output.value, token counts |
| Tool | tool.name, tool.description, input/output, risk category |
| Session | tracectrl.session_id linking all spans in a conversation |
TraceCtrlSpanProcessor automatically enriches every span with:
- Tool risk category — one of 8 categories (filesystem, network, code_execution, data_store, web_browsing, communication, system, other)
- Agent identity — framework detection and agent naming
- Session correlation — links all spans from a single conversation
Checkpoint: Sessions page shows traces with agent → LLM → tool spans. Topology page shows your agent connected to its tools and LLM provider.
Summary
What You Built
| Component | Status |
|---|---|
| TraceCtrl stack (Engine + Dashboard + Collector + ClickHouse) | Running via Docker |
| OpenClaw agent with WebChat | Configured and chatting |
| Security scan (33 checks) | Findings visible on dashboard |
| Auto-remediation | Critical findings fixed |
| Manual hardening | SSRF, sandbox, session isolation configured |
| Strands agent with TraceCtrl instrumentation | Traces and topology visible |
CLI Reference
Useful Links
TraceCtrl GitHub
Source code and issues.
OpenClaw Docs
Full OpenClaw reference.
OpenTelemetry
The observability standard TraceCtrl is built on.
Strands Agents
AWS Strands agent framework.

