macOS user guide

From a verified download to a working endpoint sensor, a live local record, and centrally searchable detections. This guide covers the public ShadowClaw 1.5.1 package and the permissions that make its three detection planes useful on a Mac.

Download this guide as a PDF

Operator edition · 22 October 2026 · ShadowClaw 1.5.1

1. Before you install

Use macOS 13 or later for the Endpoint Security host plane, an administrator account, and permission to grant Full Disk Access. The disk image supports Apple silicon and Intel Macs and includes its own Python runtime. Xcode, Homebrew and a separate Python installation are not required.

ShadowClaw observes and records; it does not block the activity it finds. Plane A observes processes and compute, Plane B connects processes to network activity, and Plane C observes host actions. Planes A and B operate with the sensor; full Plane C collection is an explicit opt-in and needs both root and Full Disk Access.

Allow time for installation, the synthetic checks, and a controlled live test. Optional Grafana/Loki and Collector downloads require network access and additional disk space. The built-in dashboard needs neither.

This public guide includes installation, permission, transport and operational settings. Detection weights, reporting thresholds and private detection rules remain outside its scope. Do not replace the installed configuration with an example fragment.

2. Download and verify

In your browser and Finder

1. Open shadowclaw.tech in Safari or your preferred browser. In Binaries & user guides, choose Download for macOS. Save the disk image in Downloads.
2. Choose SHA-256 checksums in the same section and save that file beside the disk image. You can also use these direct links: macOS disk image and SHA256SUMS.
3. In Finder, open Downloads and confirm both files are present. Verify the checksum before opening the disk image. Finder does not provide a built-in SHA-256 comparison, so use the short Terminal check below.

In Terminal

Open Applications > Utilities > Terminal, or press Command+Space, type Terminal, and press Return:

cd ~/Downloads
shasum -a 256 ShadowClaw-1.5.1.dmg
cat SHA256SUMS

Compare all 64 hexadecimal characters with the manifest entry for exactly ShadowClaw-1.5.1.dmg. Stop and download again if they differ. The manifest also lists other platforms; compare the entry for your file. A checksum detects a damaged or changed download; this package is unsigned and is not Apple-notarized.

3. Install and enable the three planes

Guided installation in Finder

1. Double-click ShadowClaw-1.5.1.dmg in Finder. In the disk-image window, drag ShadowClaw.app onto the Applications shortcut.
2. Open Finder > Applications and double-click ShadowClaw. Dragging alone does not install or start the sensor. If macOS blocks this trusted download, open Apple menu > System Settings > Privacy & Security, find the blocked-app notice and select Open Anyway, then confirm the per-app prompt. Do not disable Gatekeeper globally.
3. In the ShadowClaw installation dialog, choose Install and authenticate using the standard macOS administrator prompt. Choosing Quit cancels setup.
4. At Do you want to start ShadowClaw detection?, choose Start Detection. Not Now leaves the CLI installed without starting the background service.

Grant Full Disk Access in System Settings

The guided app checks this permission before it starts the service. If access is missing, it opens the settings pane, reveals the interpreter in Finder, and copies its path to the clipboard:

/usr/local/libexec/shadowclaw/Python.framework/Versions/3.13/bin/python3

1. In System Settings > Privacy & Security > Full Disk Access, select + and authenticate if asked.
2. In the file chooser, press Command+Shift+G. Paste the interpreter path shown above, press Return, select the executable and choose Open.
3. Turn on the switch for the added interpreter. If macOS requests a quit/reopen action, complete it. Return to the ShadowClaw permission dialog and choose OK so the app can recheck access and continue.
4. Read the result. If it still reports that access is missing or the host plane is degraded, do not mark Plane C complete. Confirm you added the bundled interpreter rather than only Terminal or ShadowClaw.app.

The Do you want to see the detections? dialog then offers:

Button	What happens
Open Dashboard	Starts the built-in live ledger view and opens your browser. A Terminal window hosts the viewer and may request your administrator password to read the system ledger. No extra download is needed.
Set Up Grafana	Opens a Terminal window for the Grafana/Loki download and setup. Watch it for download, checksum or startup failures; keep it open until setup completes.
Skip	Leaves detection running and shows the status report. You can open a dashboard later.

Keep the closing report when shown, and read any warnings before dismissing it. After installation, eject the disk image in Finder. Reopening Applications > ShadowClaw can offer dashboard setup again; when Grafana already answers on its default port, the app shows its status report instead.

Manual package and Terminal alternative

The .pkg inside the disk image is an alternative for manual installation. It installs the same payload but does not start detection. After installing it, grant Full Disk Access, then enable host collection in the existing configuration:

sudo cp /etc/shadowclaw/shadowclaw.json \
  /etc/shadowclaw/shadowclaw.json.before-guide
sudo /usr/local/libexec/shadowclaw/Python.framework/Versions/3.13/bin/python3 - <<'PY'
import json
from pathlib import Path
p = Path('/etc/shadowclaw/shadowclaw.json')
settings = json.loads(p.read_text())
settings['enable_esf'] = True
p.write_text(json.dumps(settings, indent=2) + '\n')
PY
sudo /usr/local/libexec/shadowclaw/enable-daemon.sh

For an already running daemon, apply subsequent configuration changes with:

sudo launchctl kickstart -k system/com.mikestorm.shadowclaw

If you declined Full Disk Access, leave Plane C recorded as incomplete. Running as root alone does not settle that permission check.

To correct a deferred permission grant, use the System Settings steps above, set enable_esf with the merge command, and restart the daemon. Reopening the app while the daemon is already loaded does not repeat the initial permission flow. The app is a guided setup launcher, not a persistent menu-bar service controller.

4. Verify installation and service status

Graphical checks

Open Applications > ShadowClaw to revisit the guided setup/status flow. A report saying the stack is up is an initial service-registration check; it does not prove that every plane is collecting. Open the dashboard it reports and look for recent records from this Mac after your test activity.

For a process check, open Applications > Utilities > Activity Monitor, choose View > All Processes, and look for the bundled Python process. Inspect its details and open files for the ShadowClaw installation path; other Python applications can run on the same Mac. Activity Monitor shows process liveness and resource use, not detection coverage. Do not use Force Quit as the normal way to stop a service managed by launchd.

For setup diagnostics, use Finder > Go > Go to Folder (Command+Shift+G), enter ~/Library/Logs/ShadowClaw, and open first-run.log in Console or TextEdit. Service logs are under /var/log/shadowclaw; access may require administrator privileges. Use the commands below for definitive service and acquisition checks.

Terminal checks

/usr/local/bin/shadowclaw --version
/usr/local/bin/shadowclaw --about
/usr/local/bin/shadowclaw --verify
sudo /usr/local/bin/shadowclaw --self-test
sudo launchctl print system/com.mikestorm.shadowclaw
sudo tail -n 80 /var/log/shadowclaw/sensor.log
sudo tail -n 80 /var/log/shadowclaw/sensor.err.log

Expect version 1.5.1, successful matrix completion, a running launchd job with a PID, live processes, and a ready host-plane probe. Inspect the startup banner for the configuration file actually loaded and the host-plane state. The system policy should be /etc/shadowclaw/shadowclaw.json. Resolve permission warnings before calling all three planes verified.

The service uses the system ledger at /Library/Application Support/ShadowClaw. An ordinary unprivileged run uses ~/Library/Application Support/ShadowClaw. Use sudo consistently when viewing the service's records; the two directories are separate histories.

5. Test Planes A, B and C

What each check establishes

Check	Evidence to keep	What it establishes
--version and --about	Version and attribution output	The installed command runs the expected payload.
--verify	All scenarios pass; command exits successfully	Synthetic inputs exercise the detector logic for Planes A, B, and C, including benign cases. It does not create live ledger findings.
--self-test	Per-plane lines, host-plane status, process and socket counts	The current execution context can reach the platform acquisition mechanisms. Read every plane line, even when the final line says PASS.
A bounded live run	Startup banner and verbose poll lines	The sensor actually collects processes, connections and host events on this endpoint.
A controlled AI session	Time, host, process, provider and matching ledger entry	The real workload reached a recorded finding.
Dashboard and destination search	The matching host, time and event	The record reached each configured presentation or central collection path.

Exercise the three planes

Use an endpoint you administer and an approved test account. Before starting, record the host name, time, AI application, provider and expected activity. Use test prompts and disposable files. Keep credentials out of commands and transcripts.

1. Plane A - process and compute. During the bounded run below, open your approved local model runtime, if one is available, and run an ordinary inference request. Confirm that the live sample has processes and that verbose polls continue. Look for the runtime in the self-test output and for any corresponding finding. A busy process alone is not a promised detection; --verify supplies the repeatable logic check when no model runtime is installed.
2. Plane B - network. Use an approved AI client to make a real request to its provider while the sensor is running. Record which application and provider you used. Match the process, provider or endpoint, and time in the ledger. A generic website fetch is not an equivalent test of AI-client attribution.
3. Plane C - host activity. While the bounded sensor runs, open another terminal and launch a harmless child process with the command shown below. Inspect the host-plane startup line and verbose esf= event counts. The name esf is used in the CLI and telemetry across all three platforms. Nonzero counts demonstrate host-event intake; they do not certify every subscription or tactic. Keep any DEGRADED or UNAVAILABLE result as an unresolved acceptance item.

A harmless shell command is not expected to become an agent-tactic finding. The synthetic matrix tests the detection decisions without creating accounts, changing persistence, or touching credentials. To validate a real host-plane alert, use your organization's approved lab exercise and correlate its resulting shadowclaw.agent.activity and finding events. Do not declare that alert path verified solely because the service is running.

Acceptance record

Record a separate outcome for each plane: verified, degraded, failed, or not exercised. Retain the version, host, execution identity, test time window, matrix result, per-plane status, ledger verification result, and matching destination event. An empty ledger on an idle host is possible; it is not evidence of full coverage. If a declared workload produces no expected finding, keep that test unresolved and use the troubleshooting section rather than changing detection settings to manufacture a pass.

Run a bounded diagnostic session

Stop the service before a foreground sensor uses its ledger. This temporarily stops monitoring; do it during your test window. In the first terminal:

sudo /usr/local/libexec/shadowclaw/disable-daemon.sh
sudo /usr/local/bin/shadowclaw \
  --config /etc/shadowclaw/shadowclaw.json \
  --ledger-dir '/Library/Application Support/ShadowClaw' \
  --esf --verbose --duration 120

While it runs, perform the approved AI workload and launch a harmless child in a second terminal:

/bin/sh -c 'printf "ShadowClaw host-event check\n"'

Read the startup host-plane line and the processes=, connections= and esf= values in successive polls. Preserve the final export summary: otlp: ... sent, ... failed reports HTTP attempts, not Splunk indexing. If no receiver is configured yet, export failures are expected until sections 7 or 8 are complete. The ledger still records findings locally.

Restore persistent monitoring even if the test failed or you interrupted it:

sudo /usr/local/libexec/shadowclaw/enable-daemon.sh
sudo launchctl print system/com.mikestorm.shadowclaw

6. View the live ledger and built-in dashboard

Open and read the graphical view

1. Open Applications > ShadowClaw and choose Open Dashboard when the dashboard-choice dialog appears. Keep its Terminal window open and enter your administrator password there if requested. The app opens the token-bearing local URL in your browser.
2. If Grafana is already running and the app instead shows its status report, use the Terminal --dashboard command below to launch the built-in view. Copy the complete URL it prints into the browser address bar.
3. Read the report's time range and ledger information. Locate your test process and compare its last-seen time, severity and provider/endpoint evidence with your recorded test. The page refreshes automatically. A browser tab being open does not by itself mean new findings are arriving.
4. Use the browser's Find command (Command+F) to locate a known process or provider. The built-in view is read-only; use the ledger commands for alternate time windows and CSV/JSON/HTML exports.
5. To close the viewer, press Control+C in the Terminal window that hosts it. This stops the dashboard server, not the background detection service. Closing only the browser tab leaves the viewer running.

Watch and verify from Terminal

sudo /usr/local/bin/shadowclaw --ledger path
sudo /usr/local/bin/shadowclaw --ledger --since 1h
sudo /usr/local/bin/shadowclaw --ledger watch --since 15m

watch follows the local record; Ctrl+C stops only the viewer. It can run beside the service. Compare time, process, user, provider or endpoint, and severity with the test you declared. Episodes fold repeated observations into a readable session; raw events retain the observations.

Check the chain and export a portable report:

sudo /usr/local/bin/shadowclaw --ledger verify
sudo /usr/local/bin/shadowclaw --ledger export \
  --since 24h --format html --out /tmp/shadowclaw-report.html
sudo /usr/local/bin/shadowclaw --dashboard

Open the complete token-bearing loopback URL printed by --dashboard in your normal browser. Keep the terminal open; Ctrl+C stops this viewer. If its port is occupied, add --dashboard-port 0 to select a free one. This is a live view of the ledger, separate from Grafana, and requires no export service. Protect reports because they identify host activity. A valid hash chain checks the stored record's integrity, not whether every possible activity was observed.

7. View detections in Grafana

Use the app's optional native stack

For graphical setup, open Applications > ShadowClaw and choose Set Up Grafana in the dashboard-choice dialog. Allow its Terminal setup window to finish; it downloads and verifies the components, provisions the dashboard and updates the sensor's export destination. If Grafana is already detected, the app shows its status report instead of that choice.

Open the dashboard URL from the report in your browser. In Grafana, choose Dashboards, locate the ShadowClaw detections dashboard, and open it. Use the time picker at the upper right to choose Last 15 minutes, then select Refresh after running your approved workload. Expand the relevant log row and compare host, process, provider and time with the ledger. For a custom query, open Explore, select the Loki datasource and paste the LogQL query below. On the native app stack, viewing is anonymous; editing requires the generated administrator credential.

If you selected Grafana/Loki during the guided installation, these Terminal checks provide component status:

bash ~/.shadowclaw-o11y/stack.sh status
bash ~/.shadowclaw-o11y/status.sh

Open the dashboard URL printed by status.sh. The usual Grafana address is http://127.0.0.1:3000; configured ports may differ. The app provisions a datasource and dashboard and sets the sensor's Loki export URL. Viewer access is anonymous on loopback. Administrative changes use the generated password in ~/.shadowclaw-o11y/grafana-admin-password. Keep it private.

To restart a stopped stack, use bash ~/.shadowclaw-o11y/stack.sh start. This stack is user-managed; check it again after a reboot. Setup and component logs are under ~/.shadowclaw-o11y/logs.

Alternative: the public Compose stack

If you did not choose the app's stack, install Docker Desktop and start it. Use a separate working folder. Do not run both local stacks on the same ports.

mkdir -p ~/shadowclaw-dashboard
cd ~/shadowclaw-dashboard
curl -fLO https://shadowclaw.tech/assets/user-guides/observability.zip
unzip observability.zip
bash
read -r -s -p 'New Grafana admin password: ' GRAFANA_ADMIN_PASSWORD
printf '\n'
export GRAFANA_ADMIN_PASSWORD
docker compose config --quiet
docker compose up -d
docker compose ps
unset GRAFANA_ADMIN_PASSWORD

Use a strong password. The explicit bash works with the prompt syntax above on Macs whose normal shell is zsh. Re-supply the variable for later Compose commands that require configuration interpolation. Log in to the public operator dashboard with this password.

In the existing /etc/shadowclaw/shadowclaw.json, change only otlp_endpoint to http://127.0.0.1:3100/otlp, emit_otlp_logs to true, and emit_otlp_metrics to false. For example, reuse the Python merge pattern in section 3 with these three keys. Restart the daemon with launchctl kickstart from section 3. Run another approved workload and verify a fresh row.

Read the Grafana dashboard

The optional local stack opens at http://127.0.0.1:3000. Sign in as admin with the password you supplied, then open Dashboards > ShadowClaw > ShadowClaw - operator overview. Its direct path is /d/shadowclaw-operator. The macOS app's native setup installs its own, larger ShadowClaw dashboard; use the URL printed by that setup instead.

Set the time range to Last 15 minutes and refresh. The public operator dashboard shows findings, provider observations, agent activity, and coverage records in separate panels. Expand a log row to inspect its host and process. Use Explore, select the ShadowClaw Loki datasource, and query:

{service_name="shadowclaw"}
  | json
  | event_name="shadowclaw.finding.recorded"

For host-plane observations, change the event filter to shadowclaw.agent.activity. For periodic coverage records, use shadowclaw.ktp.risk_factors and inspect degraded_inputs. An empty agent-activity panel is not a health check. A fresh coverage record shows that logs are arriving; it does not establish full host-plane coverage.

The datasource connects to http://loki:3100 inside the Compose network. The endpoint sensor connects to http://127.0.0.1:3100/otlp on the host. Those addresses serve different callers. The sensor appends /v1/logs. Loki does not accept sensor metrics at that path, so direct-to-Loki configuration must set emit_otlp_metrics to false.

The downloadable stack is for local evaluation, with ports published only on loopback and data in named Docker volumes. It is not a production fleet service. docker compose down stops it and preserves those volumes; adding --volumes deletes the stored dashboard and log data. For a central deployment, use your managed Grafana/Loki service with authentication, TLS, retention and backup policies. Loki's OTLP documentation covers ingestion.

8. Deliver detections centrally with OTLP and Splunk

For a graphical Splunk workflow, have your Splunk administrator configure HTTP Event Collector and the destination events index in Splunk Web, then provide the endpoint and token through your approved secret channel. After configuring the Collector below, open Search & Reporting, select Last 15 minutes, paste the verification search and choose Search. Expand a matching result to inspect its fields. Collector and sensor transport configuration still require the file/service steps below; ShadowClaw.app has no Splunk configuration form.

The delivery path

Use this path for a central destination such as Splunk:

ShadowClaw -> local OpenTelemetry Collector -> HTTPS -> Splunk HEC
          -> durable local ledger

ShadowClaw sends OTLP/HTTP JSON. Splunk HEC uses a different protocol, so a Collector performs the conversion. Do not point otlp_endpoint at a HEC URL. Use one sensor and one Collector to fan out to multiple destinations; do not start a second sensor against the same ledger.

The sensor accepts plaintext HTTP only on loopback. For a remote OTLP receiver, use an HTTPS base URL with a trusted certificate. Put backend tokens, custom authentication and client-certificate configuration in the Collector. The sensor does not expose those Collector authentication settings.

Prepare Splunk and the Collector

1. Ask your Splunk administrator for an enabled HEC token permitted to write to a dedicated events index, its exact HTTPS HEC URL, and the appropriate CA trust chain. Use the endpoint supplied for your Splunk Enterprise or Cloud deployment; do not assume a Cloud port or hostname.
2. Install the OpenTelemetry Collector Contrib distribution for the host, following its official installation instructions. The splunk_hec exporter is in Contrib. The example below targets the repository's Collector baseline, 0.158.0; validate it with the version you deploy.
3. Download collector-splunk.yaml, or save the following complete configuration as that filename. This logs-only path carries all ShadowClaw log event types. Configure the sensor with emit_otlp_logs: true and emit_otlp_metrics: false for this example.

# ShadowClaw public operator example: logs to a Splunk events index.
# OpenTelemetry Collector Contrib 0.158.0. No detection rules or secrets.
receivers:
  otlp:
    protocols:
      http:
        endpoint: 127.0.0.1:4318

processors:
  batch:
    timeout: 5s

exporters:
  splunk_hec:
    endpoint: ${env:SPLUNK_HEC_ENDPOINT}
    token: ${env:SPLUNK_HEC_TOKEN}
    index: ${env:SPLUNK_HEC_INDEX}
    source: shadowclaw
    sourcetype: shadowclaw:otel
    tls:
      insecure_skip_verify: false
    sending_queue:
      enabled: true
      queue_size: 1000
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 300s

service:
  pipelines:
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [splunk_hec]

Set SPLUNK_HEC_ENDPOINT, SPLUNK_HEC_INDEX and SPLUNK_HEC_TOKEN in the Collector's environment using the platform commands below. The token stays out of the YAML file. A shell environment belongs to that shell: a Collector installed as a service needs the same values supplied through its service configuration or secret manager.

TLS verification remains enabled. If your HEC certificate uses a private CA, add ca_file: /absolute/path/to/ca.pem under the exporter's tls mapping (use the real local path on Windows). A certificate error is a trust or hostname problem to fix, not a reason to set insecure_skip_verify: true.

See the Contrib HEC exporter reference for supported settings.

Keep Grafana while also sending to Splunk

If the local Loki stack is running, add this second exporter to the same Collector file:

exporters:
  # Keep the existing splunk_hec exporter here too.
  otlp_http/loki:
    endpoint: http://127.0.0.1:3100/otlp

Then change service.pipelines.logs.exporters to [splunk_hec, otlp_http/loki]. Merge into the existing exporters mapping; do not create two YAML keys named exporters. Run the Collector on the endpoint host for these loopback addresses to work. The sensor now points only to http://127.0.0.1:4318, and the Collector sends the same logs to both backends. If that port is already owned by DefenseClaw or another Collector, extend the existing pipeline or choose another port and update the sensor to match.

For metrics, add a metrics pipeline and an appropriate metrics backend before setting emit_otlp_metrics back to true. In Splunk, use a separately configured metrics index/exporter. Do not send metrics to the events index in this example or to Loki.

Verify receipt in Splunk

First search the events index you configured, over the last 15 minutes:

index=YOUR_EVENTS_INDEX sourcetype="shadowclaw:otel"
| spath
| table _time host event_name process_name pid providers severity

The example exporter sends the sensor's flat JSON body as the event. Find a fresh shadowclaw.ktp.risk_factors record to check the log route even on an idle host. Then perform the approved Plane B workload again and narrow the search:

index=YOUR_EVENTS_INDEX sourcetype="shadowclaw:otel"
| spath
| search event_name="shadowclaw.finding.recorded"
| table _time host process_name pid providers endpoints severity

Match the host, process, provider and time against the local ledger. Use event_name="shadowclaw.agent.activity" for tactics and event_name="shadowclaw.provider.reached" for provider observations. Keep those event types separate when counting detections. If an existing organization pipeline wraps the body, inspect a raw event and adapt the spath input to that wrapper before applying these searches.

The local ledger is written before export. Failed delivery does not automatically replay old ledger entries when connectivity returns. The example Collector has a bounded in-memory queue and retries; it is not durable across Collector restarts. For production, configure persistent Collector storage and an independently tested recovery/backfill procedure. A fresh matching event at the destination is the acceptance criterion, not just a reachable port or a running Collector.

Start the local Collector on macOS

After installing otelcol-contrib, open a Bash shell in a dedicated configuration folder. Replace the example endpoint and index with your administrator's values:

bash
curl -fLO https://shadowclaw.tech/assets/user-guides/collector-splunk.yaml
export SPLUNK_HEC_ENDPOINT='https://splunk.example.com:8088/services/collector'
export SPLUNK_HEC_INDEX='YOUR_EVENTS_INDEX'
read -r -s -p 'Splunk HEC token: ' SPLUNK_HEC_TOKEN
printf '\n'
export SPLUNK_HEC_TOKEN
otelcol-contrib validate --config=collector-splunk.yaml
otelcol-contrib --config=collector-splunk.yaml

Only start after validation succeeds. Leave that terminal running during evaluation. In the sensor's existing configuration, merge these export settings and restart the daemon:

{
  "otlp_endpoint": "http://127.0.0.1:4318",
  "emit_otlp_logs": true,
  "emit_otlp_metrics": false
}

This fragment is not a replacement configuration. Preserve enable_esf and other existing settings. Recheck the loaded config, repeat the live workload, and verify the matching event in Splunk. After the foreground Collector stops, unset SPLUNK_HEC_TOKEN. For unattended operation, install the Collector as a managed service with its environment and restart policy configured.

9. Troubleshoot by following the record

Symptom	Check and recovery
shadowclaw not found	Use /usr/local/bin/shadowclaw. Confirm the app was opened after dragging it into Applications.
Daemon missing or stopped	Run enable-daemon.sh; inspect launchctl print and both sensor log files.
Plane C unavailable	Confirm macOS 13+, root, Full Disk Access for the bundled interpreter, enable_esf: true, then restart and rerun the probe.
Service runs but ledger appears empty	Run the elevated shadowclaw --ledger path command above; confirm system versus per-user history and the test time window.
Duplicate observations	Stop extra foreground sensors; use --ledger watch for viewing instead.
Grafana says No data	Check time range, Loki datasource and container/native logs. Query coverage records first, then the correct event type.
OTLP 404	Check the base URL: Collector ends at :4318; Loki ends at :3100/otlp. Do not append /v1/logs yourself. Disable metrics for Loki/logs-only pipelines.
Splunk has no fresh event	Check Collector errors, HEC token/index authorization, TLS trust and the search time window. Local ledger success does not prove delivery.

10. Routine operation, upgrade and removal

Check service state, fresh coverage records, ledger verification and destination receipt regularly. Monitor free disk space for the ledger and optional observability storage. Review degraded_inputs alongside detection counts. Preserve an acceptance record after permission, OS or configuration changes.

Before upgrading, verify the new download, preserve the configuration and take a consistent ledger backup under your evidence-handling procedure. Use a SQLite-aware backup or stop the sensor before copying the complete ledger directory. Install the new package, confirm existing policy was preserved, and repeat sections 4-8.

To stop monitoring while keeping the installation:

sudo /usr/local/libexec/shadowclaw/disable-daemon.sh

To remove the package while preserving evidence and policy:

sudo /usr/local/libexec/shadowclaw/uninstall.sh

Dragging ShadowClaw.app to the Trash removes the setup launcher, not the installed sensor or LaunchDaemon. Run the uninstaller first; afterwards you can remove the app from Applications in Finder. Service stop/removal and hash-chain verification have no dedicated buttons in this version, so retain the Terminal steps for those operations.

The uninstaller keeps the system and per-user ledgers and /etc/shadowclaw. Optional Grafana/Loki and Collector installations have their own lifecycle; stop them separately if no longer needed. Export required reports before removal. Do not use evidence-purge options as routine cleanup.

For more detail, read the local ledger, event schemas, and OTLP export.