Run the local observability stack
defenseclaw setup local-observability up starts the bundled OTel Collector + Prometheus, Loki, Tempo, and Grafana stack and writes its named v8 destination.
The local stack gives you 19 DefenseClaw dashboards on localhost:3000 in one command. It is meant for development and evaluation. Every port is bound to 127.0.0.1.
This story retells the walkthrough briefly. For the full page on flags, dashboards and tear-down, see Observability → Local stack.
Before you start
- Docker with Compose v2, running.
- Ports 3000, 3100, 3200, 4317, 4318 and 9090 free. There is no flag to move them.
- On Windows, Docker Desktop with Linux containers on Windows Pro, Enterprise or Education. Windows Server and WSL2-only Docker are not supported; send to an existing collector instead (Send to an OTLP collector).
Run it
Bring up the stack
defenseclaw setup local-observability upThe command starts the five containers, waits for their health checks, and adds a destination named local-observability to your observability config. A running gateway picks it up without a restart.
Print the addresses
defenseclaw setup local-observability urlGrafana: http://localhost:3000
Prometheus: http://localhost:9090
Tempo API: http://localhost:3200
Loki API: http://localhost:3100
OTLP gRPC: 127.0.0.1:4317
OTLP HTTP: 127.0.0.1:4318Open Grafana
Open Grafana and sign in as admin. The generated password is in ~/.defenseclaw/observability-stack/.grafana-admin-password. A stack that was already running with anonymous access keeps it, read-only (Viewer): to edit dashboards, rerun setup with --password. The setup summary says which mode applies.
Generate one real event
Run one agent turn, for example ask Claude Code or Codex to list the files in a folder. Dashboards fill only from real traffic; a destination test adds nothing.
Open the dashboards
Open Dashboards → DefenseClaw → Overview. Hook Connectors shows the connector's hook calls. Agent identity → Runtime Agent Directory lists the agent; click its Agent ID to open Agent360.
Check the destination
defenseclaw observability destination test local-observabilityThe test checks the connection without adding events to history or dashboard counts.
Tear it down
defenseclaw setup local-observability downdown stops the containers and keeps their data. The destination stays in your config, so the gateway keeps trying to send; add --disable-config to turn it off too. To delete the stored metrics, logs and traces, run defenseclaw setup local-observability reset --yes.
Architecture
List view for small screens. Use the expand button to open the drawing.
- Gatewaydefenseclaw-gateway
- sends OTLPOTel Collector
- OTel Collector:4317 gRPC · :4318 HTTP
- writesPrometheus
- writesLoki
- writesTempo
- Tempotraces · :3200
- queried byGrafana
- Lokilogs · :3100
- queried byGrafana
- Prometheusmetrics · :9090
- queried byGrafana
- Grafanadashboards · :3000
Keep the destination name
Do not rename local-observability. The bundled dashboards read metric labels that DefenseClaw only exports to a destination with that name. To feed the stack from a gateway on another computer, add the destination with the preset:
defenseclaw setup observability add local-otlp --endpoint <stack-host>:4317 --non-interactiveNext
- Dashboards: what each board shows and how to read empty panels.
- Observability reference: stack images, ports and
upflags. - Troubleshoot the local stack: no data, port conflicts and detaching the gateway.
- Send to Splunk: run Splunk next to this stack.
Approve risky tool calls before they fire
Trigger a native HITL approval prompt on Claude Code with a harmless HIGH-severity command, then see what happens on connectors without native ask.
Add a connector without losing audit history
Use defenseclaw setup <connector> to add or reconfigure agent wiring while preserving audit history for every connector.