Stories

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.

DefenseClaw can export to an existing telemetry stack, but the bundled local stack gives you a loopback-only environment for development and evaluation.

Quick tour: defenseclaw setup local-observability up → containers warm up → the named destination is written → restart the gateway → Grafana populates with live events.

For the full deep-dive on flags, dashboards, and tear-down, see Observability → Local stack.

What you get

Prometheus

Metrics exported through the local OTel Collector.

Loki

Canonical gateway logs with connector and severity attributes.

Tempo

Gateway and connector traces exported through OTLP.

Grafana

Fourteen provisioned DefenseClaw dashboards backed by Prometheus, Loki, and Tempo.

Run it

Bring up the stack

defenseclaw setup local-observability up

Brings up five containers via Docker Compose:

  • otel/opentelemetry-collector-contrib:0.153.0 on 127.0.0.1:4317 (gRPC) and 127.0.0.1:4318 (HTTP)
  • prom/prometheus:v2.54.1 on 127.0.0.1:9090
  • grafana/loki:3.2.0 on 127.0.0.1:3100
  • grafana/tempo:2.6.0 on 127.0.0.1:3200
  • grafana/grafana:11.3.0 on 127.0.0.1:3000

The Compose file binds all published ports to loopback by default.

Reload the gateway configuration

defenseclaw-gateway restart

Unless up was run with --no-config, it already created or updated observability.destinations[local-observability] with the selected logs/metrics/traces signals and the collector endpoint. Restart the gateway so the new destination takes effect. No connector setup command is required.

Open Grafana

Visit http://localhost:3000. The bundled Compose configuration disables the login form and grants anonymous Admin access because Grafana is loopback-only by default. If you change HOST_BIND, secure Grafana before exposing it.

Fourteen dashboards are provisioned, including Overview, Traffic, Security, Findings, Policy Decisions, HITL, Connectors, Connector Detail, Activity, Runtime, Scanners, AI Discovery, Agent Identity, and Agent 360. See Grafana dashboards for their exact queries and panels.

Tear it down

defenseclaw setup local-observability down

Stops the containers while preserving their named volumes and the configured destination. Your audit DB is untouched. To stop the stack and disable the destination in config, use:

defenseclaw setup local-observability down --disable-config

Use reset --yes only when you also intend to delete the stack's Prometheus/Loki/Tempo/Grafana data.

Architecture

OTLP logs / metrics / traces
metrics
logs
traces
Control planedefenseclaw-gateway
ConnectorOTel Collector:4317 / :4318
Evidence storePrometheus:9090
Evidence storeLoki:3100
Evidence storeTempo:3200
Evidence storeGrafana:3000
The gateway exports three signals. The local stack receives all three and Grafana joins them.

When to graduate to your own stack

The local stack is for building intuition. For production, replace each component with the equivalent in your existing telemetry estate:

  • Prometheus → your metrics platform (Datadog, New Relic, Honeycomb, ...).
  • Loki → your log aggregator (Splunk, Datadog Logs, ...).
  • Tempo → your tracing backend (Honeycomb, Tempo, Jaeger, ...).
  • Grafana → whatever your team already uses for dashboards.

Point the gateway's OTLP exporter at your collector and DefenseClaw's signals land alongside the rest of your telemetry. See the Reference / Configuration page for the full env-var list.

Approve risky tool calls before they fire

Use a safe synthetic secret file to verify native HITL approval on Claude Code, then understand the non-pausing fallback 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.