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 up

The 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.

defenseclaw setup local-observability url
Grafana:    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:4318

Open 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-observability

The test checks the connection without adding events to history or dashboard counts.

Tear it down

defenseclaw setup local-observability down

down 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

sends OTLP
writes
writes
writes
queried by
queried by
queried by
Gatewaydefenseclaw-gateway
OTel Collector:4317 gRPC · :4318 HTTP
Prometheusmetrics · :9090
Lokilogs · :3100
Tempotraces · :3200
Grafanadashboards · :3000

List view for small screens. Use the expand button to open the drawing.

  1. Gatewaydefenseclaw-gateway
    • sends OTLPOTel Collector
  2. OTel Collector:4317 gRPC · :4318 HTTP
    • writesPrometheus
    • writesLoki
    • writesTempo
  3. Tempotraces · :3200
    • queried byGrafana
  4. Lokilogs · :3100
    • queried byGrafana
  5. Prometheusmetrics · :9090
    • queried byGrafana
  6. Grafanadashboards · :3000
The gateway sends logs, metrics and traces over OTLP to the collector, which writes each signal to its own store. Grafana queries the three stores. Ports are bound to 127.0.0.1.

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

Next