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.
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 upBrings up five containers via Docker Compose:
otel/opentelemetry-collector-contrib:0.153.0on127.0.0.1:4317(gRPC) and127.0.0.1:4318(HTTP)prom/prometheus:v2.54.1on127.0.0.1:9090grafana/loki:3.2.0on127.0.0.1:3100grafana/tempo:2.6.0on127.0.0.1:3200grafana/grafana:11.3.0on127.0.0.1:3000
The Compose file binds all published ports to loopback by default.
Verify the hot-reloaded destination
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. A running gateway
hot-reloads that destination without changing its PID or interrupting active
agent sessions—even when gateway.config_reload.mode is restart. If the
gateway is stopped, the destination takes effect on its next normal start. No
connector setup command or manual gateway restart is required.
Open Grafana
Visit http://localhost:3000. New managed stacks use
the admin login; read the generated password from
~/.defenseclaw/observability-stack/.grafana-admin-password. Existing
anonymous stacks remain no-password after upgrade. Pass --password to move
one to login mode, or explicitly choose --no-password for anonymous Admin on
the managed loopback bind. The setup summary reports the effective mode and
warns whenever no-password access is active. The Loki, Tempo, and Prometheus
developer APIs are still separately loopback-only; do not expose them through
HOST_BIND without an external access-control layer.
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 downStops 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-configUse reset --yes only when you also intend to delete the stack's
Prometheus/Loki/Tempo/Grafana data.
Architecture
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.