Real failure modes across every Crawdad installer, the sidecar on macOS, Linux, and Windows, and the self-hosted fleet console, each with the symptom you see, what it means, and the fix. Every entry traces to what the installer actually does. If your issue isn't listed, contact contact@getcrawdad.dev with the exit code and the installer's output.
Jump to: Checksum failure · Sidecar won't start · Binary won't execute · Windows · Fleet console · Enrollment · Auto-updates · Uninstall
The installer downloaded the binary but its checksum didn't match the published .sha256. This is the fail-safe working, not a bug. Every installer, sidecar and fleet, fetches the checksum alongside the binary and refuses to install on any mismatch; nothing is written to disk. It means the download was corrupted or truncated (flaky network, a proxy or "security" appliance rewriting the response, a partial CDN transfer), or, far less often, that the file you received isn't the file that was published.
The fix is almost always to re-download on a clean path:
# Re-run the installer (a fresh, complete download usually verifies fine) curl -fsSL https://getcrawdad.dev/install.sh | sh # Or fetch the binary and checksum yourself and compare curl -fsSL -o /tmp/crawdad https://getcrawdad.dev/download/v1.7.1/crawdad-linux-x86_64 curl -fsSL https://getcrawdad.dev/download/v1.7.1/crawdad-linux-x86_64.sha256 shasum -a 256 /tmp/crawdad # macOS sha256sum /tmp/crawdad # Linux
If it keeps failing on the same network, a corporate proxy is likely altering the download, try a different network, or ask IT to allowlist *.getcrawdad.dev and pass it through untouched. Do not work around a persistent checksum failure by installing the binary manually; the check exists precisely so a tampered or corrupt binary never runs.
The sidecar binary installed but didn't answer on the health port (127.0.0.1:7749/v1/health) within the installer's 60-second window (the install exits with code 3). First launch legitimately takes a while, macOS Keychain setup alone can run 30–40 seconds, so the script prints a "still starting" note at 15 seconds before giving up. Most common causes:
Check what's binding it:
# Linux sudo ss -tlnp | grep 7749 # macOS sudo lsof -i :7749
Stop the conflicting process, or change Crawdad's port (set CRAWDAD_PORT=7799 in the systemd unit's Environment= line on Linux, or in the launchd plist's EnvironmentVariables block on macOS).
View the logs:
# Linux (systemd journal) sudo journalctl -u crawdad-sidecar --no-pager -n 100 # macOS (launchd logs) cat ~/Library/Logs/crawdad/sidecar.err cat ~/Library/Logs/crawdad/sidecar.log
Common errors in the logs:
Permission denied on ~/.local/share/crawdad/, directory permissions broken; remove (sudo rm -rf ~/.local/share/crawdad) and re-run install.shFailed to bind 127.0.0.1:7749, port already in use (see above)Some systems take longer to initialize than the installer's 60-second budget. Wait another 30 seconds, then retry:
curl -s http://127.0.0.1:7749/v1/health
If you get JSON back, Crawdad is healthy.
The installer ran the binary's --version smoke test and it failed. Three causes:
Confirm your platform:
# Linux and macOS uname -m
Crawdad supports arm64 (Apple Silicon, AWS Graviton, Raspberry Pi 4+) and x86_64. Other architectures aren't currently supported, email contact@getcrawdad.dev with details.
Linux binaries require glibc 2.28+. Check:
# Linux only ldd --version | head -1
glibc 2.28+ covers Debian 10+, Ubuntu 18.04+, RHEL 8+, Amazon Linux 2023.
Check:
# macOS only file /usr/local/bin/crawdad-sidecar codesign -dv /usr/local/bin/crawdad-sidecar 2>&1 | head -3
If file returns “Mach-O 64-bit executable arm64” and codesign shows the binary signed and notarized, the binary is fine, the issue is environmental.
Crawdad's auto-start service requires systemd. Distros without systemd (Alpine, OpenWrt, distroless containers, custom embedded Linux) install the binary correctly but skip service registration.
The binary works, start it manually:
/usr/local/bin/crawdad-sidecar run &
For production deployments on non-systemd init systems (OpenRC, runit, supervisord, s6), email contact@getcrawdad.dev.
install.sh tried to determine the service user's home directory and failed. Usually happens in custom Docker images, distroless containers, or embedded systems where /etc/passwd is stripped.
Workaround: explicitly set USER:
USER=root curl -fsSL https://getcrawdad.dev/install.sh | sudo sh
On a normal Linux distribution, this error is a bug, email contact@getcrawdad.dev with getent passwd $USER output and your distro/version.
Re-running install.sh is safe, it unloads the old LaunchAgent/service first and swaps the binary in place, preserving your data. If a stale process is still holding the health port (7749) or dashboard port (7750) so the reinstall's health check won't pass, stop the old sidecar by hand, then re-run:
# macOS launchctl unload ~/Library/LaunchAgents/com.crawdad.sidecar.plist sudo pkill -f crawdad-sidecar # Linux sudo systemctl stop crawdad-sidecar
Then re-run install.sh. To find whatever is holding a port, use the ss/lsof commands from the port-conflict section above.
install.sh couldn't download the binary from R2.
Ask IT to allowlist *.getcrawdad.dev and crawdad-releases.r2.cloudflarestorage.com.
curl -fsSL -o /tmp/crawdad-test https://getcrawdad.dev/download/v1.7.1/crawdad-linux-x86_64 ls -lh /tmp/crawdad-test
Should be ~29MB. If it fails, the issue is your network reaching Cloudflare. Try a different network.
Wait 5 minutes and re-run install.sh.
Crawdad currently supports:
Other OS or architecture: email contact@getcrawdad.dev.
This is Gatekeeper reacting to the macOS quarantine flag on a downloaded file. The curl … | sh install path does not set that flag, so the sidecar and its helpers normally launch without a prompt, and the signed binaries pass notarization. If you do hit it (for example after moving a binary in via a browser), clear the quarantine attribute or approve it in Settings:
# Clear the quarantine flag on a specific file sudo xattr -d com.apple.quarantine /usr/local/bin/crawdad-sidecar # Or: System Settings → Privacy & Security → "Open Anyway"
The fleet installer already strips this flag from crawdad-fleet automatically. If codesign -dv /usr/local/bin/crawdad-sidecar shows the binary signed and notarized (it should), any remaining launch failure is environmental, not a signing problem, see the execution section above.
The Windows installer requires an elevated shell, it registers a service and writes to Program Files. Open Windows PowerShell as Administrator (Start → type "PowerShell" → right-click → Run as administrator) and run irm https://getcrawdad.dev/install.ps1 | iex again.
The installer pulls crawdad-windows-x86_64.exe into %ProgramFiles%\Crawdad and runs it as the CrawdadSidecar service. If Windows SmartScreen or your AV/EDR quarantines the download or the service executable, the install will fail or the service won't start. Allowlist *.getcrawdad.dev and the Crawdad executable in your endpoint protection, then re-run. As with every platform, a genuine SHA-256 mismatch! (the installer exits with code 2) means the download was altered, re-download on a clean network rather than bypassing the check.
On Windows this is a warning, the service is installed regardless. Check it directly:
sc.exe query CrawdadSidecar Get-EventLog -LogName Application -Source CrawdadSidecar -Newest 20
If the service is STOPPED, start it with Start-Service CrawdadSidecar and re-check the health endpoint at http://127.0.0.1:7749/v1/health.
The fleet installer's preflight refuses to run if either the console port (9000) or the relay port (8800) is taken. Find and stop the conflicting process, or move the conflict, then re-run:
# Linux sudo ss -tlnp | grep -E ':9000|:8800' # macOS sudo lsof -i :9000 -i :8800
Preflight also requires ≥100 MB free on the data directory's volume. Free some space (or point CRAWDAD_FLEET_DATA_DIR at a roomier volume) and re-run.
ERR_SSL_PROTOCOL_ERROR or binary garbageYou opened http://localhost:9000. The console speaks HTTPS only, plain HTTP to the TLS port produces exactly this error. Open https://localhost:9000 (with the https://).
Expected. The console serves the internal CA's self-signed certificate. Proceed past the warning, or trust the root permanently with the security add-trusted-cert (macOS) / update-ca-certificates (Linux) command the installer prints, pointing at <data-dir>/internal_ca_root_cert.pem.
ck_) keyOnly the key's SHA-256 hash is stored, it cannot be recovered, only rotated. On the console host:
crawdad-fleet operator list crawdad-fleet operator reset-key --id <operator-id> # prints a new key once
The service is installed even when first-boot health times out. Check the logs:
# Linux (system install) journalctl -u crawdad-fleet -f # Linux (per-user install) journalctl --user -u crawdad-fleet -f # macOS tail -f <log-dir>/crawdad-fleet.log
On a host without systemd, the installer skips the service and prints the exact command to run crawdad-fleet manually, that's expected, not a failure.
Enrollment (crawdad enroll, or the ENROLLMENT_KEY/CONSOLE_URL/CA_FINGERPRINT trio pushed by the installers) can fail for a handful of specific, recoverable reasons. The exact message tells you which:
--ca-fingerprint sha256:… (fetch it from the console, below), or --insecure for dev only.sha256:. Copy it exactly as the console emits it.--console-url, the console is down, or a firewall is in the way. Confirm the URL (with https:// and the port) is reachable from the device.et_ tokens are single-use and time-limited. Generate a fresh one in the console (Add device) and retry. For fleets, a reusable ek_ key enrolls many devices.Get the current CA fingerprint any time:
curl -fsk https://<console-host>:9000/api/v1/enrollment/ca-fingerprint # or, on the console host: crawdad-fleet ca export --out ca.pem
The self-updater verifies before it swaps, mandatory SHA-256, plus codesign --verify on macOS, and it only trusts an Ed25519-signed release manifest. If any check fails it refuses the update and keeps the running version. A refused update is the fail-safe doing its job, not a broken install; you stay on the known-good binary.
Run crawdad status to see update state. Two states need action:
/usr/local/bin isn't writable by the service. crawdad status prints the exact sudo cp … && sudo chmod 755 … command to apply it; on macOS the privileged update helper normally does this for you, so this state usually means that helper isn't installed.macOS: a 1.7.0 install that won't start or update. On macOS a 1.7.0 sidecar could fail to start under launchd if an earlier run as root left root-owned files behind (a posix_spawn / EX_CONFIG error, or a crash on the data directory), which also blocked the in-app update. This is fixed in 1.7.1. If a Mac is stuck on 1.7.0, update it by re-running the installer, curl -fsSL https://getcrawdad.dev/install.sh | sh, which stops any running sidecar, reclaims those files, moves logs to ~/Library/Logs/crawdad/, and starts cleanly, rather than waiting on the in-app updater. A healthy install updates in place, no reinstall needed.
If this device is in Enforce mode, release the egress lock first. Under Enforce, Crawdad installs a persistent OS default-deny egress lock (pf on macOS, iptables on Linux) that is designed to survive a sidecar kill, so removing the sidecar without releasing it can leave a default-deny rule in place. Return the device to Monitor first: while the sidecar is alive, POST /api/v1/mode/enforcement with {"mode":"monitor"} (admin token); or if it is already stopped, sudo crawdad enforce release --reason "uninstall". Then run the uninstaller. See the Enforce mode guide. (Devices in the default Monitor mode need no such step.)
Your data is preserved by default. Every uninstaller removes the binary, service, helper components, shell config, and logs, but leaves the data directory (keys, certs, audit log) in place so you can reinstall. Add --purge to also erase the data.
# Remove Crawdad, keep data curl -fsSL https://getcrawdad.dev/uninstall.sh | sh # Remove Crawdad and erase all data (keys, certs, audit log) curl -fsSL https://getcrawdad.dev/uninstall.sh | sh -s -- --purge
The script removes the crawdad symlink and crawdad-sidecar binary, the LaunchAgent (macOS) or systemd unit (Linux), the update/SE/biometric/workspace helper components, the ANTHROPIC_BASE_URL line from your shell profile, and the logs. It is safe to run under an RMM, it continues past individual failures and reports what it couldn't remove.
# PowerShell as Administrator
irm https://getcrawdad.dev/uninstall.ps1 | iex
Removes the CrawdadSidecar service, the %ProgramFiles%\Crawdad directory, and the PATH entry. Data at %APPDATA%\crawdad is preserved; append --purge to remove it too.
curl -fsSL https://getcrawdad.dev/fleet-install.sh | sh -s -- --uninstall
Stops and removes the crawdad-fleet service and binary. The data directory is always preserved (it holds your operators, internal CA, and enrollment records), the uninstaller prints the exact rm -rf <data-dir> command if you want to erase it. Run it the same way you installed (as your user for a per-user install, or with sudo for a system install) so it targets the right paths.
A default install (cooperative proxy, Monitor mode) is fully reversed by the commands above. Two leftovers apply only if you changed a default, and no uninstaller touches them:
Crawdad Interception CA to your OS trust store; the default cooperative-proxy install adds no certificate. If you enabled it, remove it by hand (or disable interception in-app before uninstalling):
# macOS sudo security delete-certificate -c "Crawdad Interception CA" /Library/Keychains/System.keychain # Linux sudo rm -f /usr/local/share/ca-certificates/crawdad-interception-ca.crt && sudo update-ca-certificates --fresh # Windows (PowerShell as Administrator) certutil -delstore Root "Crawdad Interception CA"
--purge leaves it. Remove it with:
security delete-generic-password -s com.crawdad.sidecar \ -a "storage-master-key:$HOME/Library/Application Support/crawdad"On Linux and Windows the master key is file-backed inside the data directory, so
--purge already clears it, no separate step.On WSL2, uninstall is the Linux path run inside the distro; deleting the whole distro (wsl --unregister <Distro>) removes everything at once.
Email contact@getcrawdad.dev with:
uname -a)curl -s http://127.0.0.1:7749/v1/health (or "no response")~/Library/Logs/crawdad/sidecar.log and ~/Library/Logs/crawdad/sidecar.errsudo journalctl -u crawdad-sidecar --no-pager -n 100We respond within 24 hours.