Install guide

A complete walkthrough of every way to install Crawdad, so you know exactly what to expect before you run anything. For each path this page narrates what the installer prints, where the binary lands, what service it registers, and how to confirm it's running. Everything here is drawn from the installer scripts themselves.

Two things install with one command each. The sidecar (crawdad-sidecar) is the local security proxy that protects one machine's agents; you install it on every machine you want protected. The fleet console (crawdad-fleet) is the optional self-hosted control plane that manages many enrolled sidecars; you install it once, on the host that will run your fleet. This guide covers both.

1 Sidecar, macOS

curl -fsSL https://getcrawdad.dev/install.sh | sh

Open Terminal (Cmd+Space, type "Terminal", Enter) and paste the command. Here is what happens, in order:

• It detects your platform and picks the matching signed binary (crawdad-macos-arm64 on Apple Silicon, crawdad-macos-x86_64 on Intel).
• It downloads the binary, fetches the published .sha256, and verifies the checksum. A mismatch aborts the install, nothing is written.
• It installs the binary to /usr/local/bin/crawdad-sidecar and creates a crawdad symlink beside it. If /usr/local/bin isn't writable, it asks for your Mac password once (sudo).
• It runs the binary's --version as a smoke test, so any architecture or library problem surfaces immediately.
• On Apple Silicon it also installs the Secure Enclave helper, the privileged auto-update helper, and the sandboxed-workspace components. Each is checksum-verified; if one can't be fetched it prints a warning and continues, the sidecar still runs.
• It writes a LaunchAgent at ~/Library/LaunchAgents/com.crawdad.sidecar.plist and loads it. The service starts now and again automatically every time you log in.
• It waits for the sidecar to answer on http://127.0.0.1:7749/v1/health. First launch can take up to 60 seconds while macOS sets up the Keychain, the script tells you it's still starting.
• It appends export ANTHROPIC_BASE_URL=http://localhost:7748 to your ~/.zshrc (or ~/.bashrc) inside a marked # >>> crawdad >>> block, and opens the dashboard at http://localhost:7750.

  Crawdad v1.7.1
  Platform: darwin/arm64
  Downloading crawdad-macos-arm64...
  ✓ SHA-256 verified
  ✓ Binary installed
  ✓ 'crawdad' command created
  ✓ Binary runs (crawdad 1.7.1)
  ✓ Service registered (starts on login)
  ...workspace + helper components...
  Waiting for Crawdad to start...
  ✓ Crawdad /v1/health OK
  ✓ Shell configured (/Users/you/.zshrc)

  ✓ Crawdad installed and protecting your agents
  Dashboard: http://localhost:7750

Where things are: binary at /usr/local/bin/crawdad-sidecar (with the crawdad command symlinked next to it); data directory at ~/Library/Application Support/crawdad/ (created 0700, the sidecar refuses a group- or world-readable data dir); logs at ~/Library/Logs/crawdad/sidecar.log and ~/Library/Logs/crawdad/sidecar.err.

Intel Macs run pattern-based detection only, ML requires Apple Silicon, and the installer prints a note saying so. Everything else is identical.

2 Sidecar, Linux

curl -fsSL https://getcrawdad.dev/install.sh | sh

Same command, same download-and-verify flow as macOS. The differences are the service and the data location:

• It installs a systemd unit at /etc/systemd/system/crawdad-sidecar.service and enables + starts it. The service runs as root and restarts on failure. Registering the unit uses sudo.
• The data directory is /var/lib/crawdad (created 0700); logs go to /var/log/crawdad/sidecar.log and follow with sudo journalctl -u crawdad-sidecar -f.
• Supported targets are x86_64 and ARM64 with glibc 2.28+ (Debian 10+, Ubuntu 18.04+, RHEL 8+, Amazon Linux 2023). Both architectures ship full ML detection.
• On a distribution without systemd (Alpine, distroless, some containers) the binary still installs, and the script prints the exact command to run it manually instead of registering a service.

  ✓ SHA-256 verified
  ✓ Binary installed
  ✓ Systemd service installed and started (runs as root)
    Data: /var/lib/crawdad
    Logs: sudo journalctl -u crawdad-sidecar -f
  Waiting for Crawdad to start...
  ✓ Crawdad /v1/health OK

3 Sidecar, Windows

irm https://getcrawdad.dev/install.ps1 | iex

Open Windows PowerShell as Administrator (Start → type "PowerShell" → right-click → Run as administrator) and paste the command. Administrator is required, the installer declares #Requires -RunAsAdministrator because it registers a service and writes to Program Files. Here's the flow:

• It downloads crawdad-windows-x86_64.exe and its .sha256 and verifies the checksum; a mismatch aborts before anything is installed.
• It installs to %ProgramFiles%\Crawdad\crawdad.exe and creates the data directory at %APPDATA%\crawdad.
• It registers a Windows service named CrawdadSidecar (display name "Crawdad Zero-Knowledge Security Sidecar"), set to start automatically, with restart-on-failure actions, and starts it.
• It waits for http://127.0.0.1:7749/v1/health. If the service is slow to answer within 60 seconds it prints a warning (not a fatal error) with the commands to check the service and its event log.
• It adds %ProgramFiles%\Crawdad to the system PATH (open a new terminal to pick it up).

  Crawdad Installer v1.7.1 (Windows)
  Downloading crawdad v1.7.1 ...
  Verifying SHA-256 checksum ...
  SHA-256 OK
  Installed to C:\Program Files\Crawdad\crawdad.exe
  Registering Windows service ...
  Service registered (CrawdadSidecar)
  Starting Crawdad service ...
  Crawdad /v1/health OK

  Crawdad installed and protecting your agents
  Dashboard: http://localhost:7750
  Service:   sc.exe query CrawdadSidecar

4 Fleet console (self-hosted / MSP)

curl -fsSL https://getcrawdad.dev/fleet-install.sh | sh

Run this on the host that will manage your fleet. The console is a single native binary, no Docker. How you run the command decides where it installs:

What the installer does, in order:

• Preflight, checks that ports 9000 and 8800 are free, that there's at least 100 MB of disk, and that curl is present. Any failure stops the install before anything is written.
• Download + verify, fetches crawdad-fleet and checks its SHA-256. On macOS it clears the quarantine attribute so the binary runs.
• Install the service, systemd on Linux, launchd on macOS, plus log rotation.
• First-boot init, waits for https://localhost:9000/health, runs --init-admin (generates the admin signing identity) and --init-operator admin (creates the first operator and prints the operator API key once), then restarts to pick up the admin identity.
• Verify, confirms the console answers, reads the CA fingerprint, and checks the service is active. Then it prints the hand-off.

  Step 4: First-boot initialization
  Waiting for service... ready
  Initializing admin identity...
  Creating first operator...

  OPERATOR API KEY (shown ONCE — save it now):

    ck_1a2b3c4d5e6f...

  Verification
  [PASS] Operator plane responds on https://localhost:9000
  [PASS] CA fingerprint: sha256:ab12cd34...
  [PASS] systemd system service is active

  Crawdad Fleet Ready
  Console:  https://localhost:9000  (localhost-only by default)
  Relay:    wss://0.0.0.0:8800   (network-accessible, mTLS-gated)

First-run: log in

1. Open https://localhost:9000 in a browser. Type the https://, without it the browser sends plain HTTP to the TLS port and shows a confusing error.
2. The console uses the internal CA's self-signed certificate, so you'll get a one-time browser warning. Proceed past it (or trust the root CA cert, the installer prints its path and the exact security add-trusted-cert / update-ca-certificates command).
3. Paste the ck_… operator key from the installer output to log in.
4. You're in. Create a scope for your first client or environment, then enroll devices into it.

Enrolling devices, generating a per-device token or a reusable RMM key, getting the CA fingerprint, and pushing to client machines, is the full Deploy your fleet guide.

5 Confirming it's running

Sidecar

The quickest confirmation is the dashboard at http://localhost:7750, opened for you at the end of install. From your own machine it loads without any token, the sidecar sets an authentication cookie automatically for localhost, so the dashboard "just works" locally. (The hex token in the startup log is only needed for remote access or scripted API calls; crawdad rotate-token prints a fresh tokened URL.)

From the command line:

crawdad status                          # running state, device id, fleet enrollment
crawdad-sidecar --version               # prints 1.7.1
curl http://127.0.0.1:7749/v1/health    # {"status":"ok",...}

To check the service directly:

# macOS
launchctl list | grep com.crawdad.sidecar

# Linux
systemctl status crawdad-sidecar

# Windows (PowerShell)
sc.exe query CrawdadSidecar

Fleet console

curl -fsk https://localhost:9000/health                          # console is up
curl -fsk https://localhost:9000/api/v1/enrollment/ca-fingerprint # sha256:...

# Service (system install)
systemctl status crawdad-fleet          # Linux
launchctl list com.crawdad.fleet        # macOS

Anything not answering as expected is covered on the install troubleshooting page, with the symptom, what it means, and the fix for every real failure mode.

6 Uninstalling

Every path has a clean uninstaller. By default your data (keys, certs, audit log) is preserved so you can reinstall; add the purge flag to erase it.

Next: Getting started (point your agent at the proxy, trust levels, phone pairing) · Deploy your fleet (enrollment, MSP rollout) · Install troubleshooting.