Standalone ShadowClaw telemetry¶
Use this path when the separate ShadowClaw sensor should report into the Grafana and Loki stack provided by DefenseClaw. ShadowClaw exports OTLP to the stack's Collector and installs its dashboard through Grafana's API.
Legacy Python 1.5.1 setup
The profile and dashboard helper below belong to the retained ShadowClaw Python 1.5.1 source tree. They do not enable DefenseClaw's native AI Discovery Runtime planes, and are not installation instructions for ShadowClaw Go 2.x.
For packaged 1.5.1 installation, permissions, all three planes, and verification, start with the macOS, Linux, or Windows user guide. Run only one instance of a sensor against its live ledger.
Start the observability stack¶
On a per-user DefenseClaw installation that supports its bundled local stack, start Docker, then run:
up starts the stack and configures DefenseClaw's local observability destination. Review DefenseClaw's local stack documentation for current prerequisites and platform support.
The bundled Collector uses loopback ports 4317 (OTLP/gRPC) and 4318 (OTLP/HTTP). Only one Collector can own those ports: stop any competing ShadowClaw companion stack before starting this one. Docker is needed for this bundled stack; a separate Loki installation is another option for standalone ShadowClaw telemetry.
Connect ShadowClaw and install its dashboard¶
From the legacy ShadowClaw source root, with the sensor permissions already configured:
# Run one sensor with the bundled DefenseClaw export profile.
sudo python3 -m shadowclaw --config config/shadowclaw.defenseclaw.json --dns-sniffer
This example uses the legacy Unix CLI and optional DNS capture. Host-plane collection requires the platform permissions and --esf setup described in the relevant user guide; it is not enabled by the dashboard. If a packaged service is already running, configure that installation's exporter instead of starting another sensor.
In a second terminal, install the dashboard. A new DefenseClaw local stack uses an admin login and stores its generated password in the file below. These commands pass that file to the helper without printing the password:
python3 integrations/defenseclaw/install_dashboard.py --check \
--username admin --password-file "$HOME/.defenseclaw/observability-stack/.grafana-admin-password"
python3 integrations/defenseclaw/install_dashboard.py \
--username admin --password-file "$HOME/.defenseclaw/observability-stack/.grafana-admin-password"
For an existing anonymous local stack, omit the two authentication options. For another authenticated Grafana, use its own credentials.
The helper discovers the Loki datasource, creates a ShadowClaw folder, and prints the dashboard URL. Re-running updates the same dashboard. It writes through Grafana's HTTP API; it does not edit DefenseClaw's installation or provisioning files.
Use --grafana-url URL for another Grafana, --datasource-uid UID to select a datasource explicitly, and --dry-run to inspect the planned change. Authenticated Grafana deployments require credentials; consult the helper's --help for token and password-file options.
Identity and delivery¶
Standalone ShadowClaw sends service.name=shadowclaw, service.namespace=shadowclaw, and shadowclaw.* event names. Preserve those attributes through the Collector. They distinguish the standalone sensor from DefenseClaw's native ai.runtime.* records, even when both products use the same backend.
The supplied profile targets OTLP/HTTP on http://127.0.0.1:4318. Leave metrics enabled when the receiving stack has its Prometheus pipeline. See OTLP export for the standalone transport and event schemas for field definitions.
Verify the dashboard¶
- Confirm the standalone sensor's local ledger is advancing using its platform user guide.
- Open the URL printed by the installer and choose the ShadowClaw — Shadow AI Detections dashboard. Set the host and time range to the sensor you just connected.
- Check sensor health and recent findings. For provider counts, use
shadowclaw.provider.reached; a finding's headline provider does not enumerate every provider contacted. - Inspect the host-plane row only after confirming host-plane collection is active. Empty panels alone do not establish healthy coverage.
- If local evidence exists but Grafana is empty, check the receiver, exporter, Loki datasource, and time window. The standalone ledger remains local during an export outage; remote replay is a separate concern.
The bundled dashboard also contains historical comparison panels for DefenseClaw events. DefenseClaw's schema has evolved, so use its own current runtime dashboards for its native planes rather than interpreting an empty legacy comparison panel as missing runtime activity.
Remove the ShadowClaw dashboard¶
Pass the same authentication options used for installation when required. This deletes the dashboard; its Grafana folder remains. It does not stop either sensor or remove the observability stack. For the rest of a standalone removal, follow Uninstall.