Deploy your fleet

Stand up a complete Crawdad fleet — console and relay, with a built-in internal CA — with one command. Then enroll your first device and set policy.

1 Install

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

The installer checks your environment (Docker, Compose v2, ports, disk), downloads the fleet archive, runs the idempotent bootstrap (init-fleet.sh), and verifies the fleet is working.

At the end it prints your console URL, operator login key (shown once), and a ready-to-paste enroll command with the real --ca-fingerprint.

Environment override: Set CRAWDAD_FLEET_DIR to change the install directory (default: $HOME/.crawdad-fleet). Port overrides: RELAY_PORT (8800), CONSOLE_PORT (9000).

What you get

Two services on one host:

Service	Port	Purpose
Relay	8800	Opaque mTLS message router
Console	9000	Fleet management UI/API with embedded dashboard and built-in internal CA (InternalCa)

What the bootstrap does

init-fleet.sh is idempotent — safe to re-run. It performs these steps:

Generate secrets — relay management token and aggregator key → .fleet.env
Generate relay TLS cert — issues a TLS server cert for the relay via openssl (SAN: relay, localhost)
Start relay + console — Docker Compose services with health checks. The console auto-initializes InternalCa on boot (generates an Ed25519 root key and self-signed root cert, persisted in HardenedStore)
Init admin identity — --init-admin (Ed25519 keypair + cert signed by InternalCa)
Init operator — --init-operator admin (creates first operator, prints API key once)
Restart console — picks up admin identity

2 Log in to the console

Open http://localhost:9000 and log in with the operator key from the installer output.

3 Create a scope and add a device

In the console, create a scope (e.g. “Production”)
Go to the Control lens
Enter a device ID and click Add device
The console generates a single-use token and shows a copy-paste enrollment command with the CA fingerprint included

4 Enroll the device

On the target machine (where the sidecar is installed):

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

crawdad enroll \
  --token et_TOKEN \
  --console-url https://fleet-host:9000 \
  --ca-fingerprint sha256:FINGERPRINT

Replace with the values from the console’s copy-paste command. The --ca-fingerprint pin verifies the root CA before the device trusts anything — see Enrollment for the trust model.

5 Set policy

In the console, create a policy template on the scope (Control lens → policy section). The device inherits it immediately. The device is now enrolled, connected via mTLS, and receiving fleet commands.

Day-2 operations

# View logs
cd ~/.crawdad-fleet && docker compose -f docker-compose.fleet.yml logs -f

# Stop the fleet
cd ~/.crawdad-fleet && docker compose -f docker-compose.fleet.yml stop

# Start the fleet
cd ~/.crawdad-fleet && docker compose -f docker-compose.fleet.yml up -d

# Uninstall (destroys all data)
curl -fsSL https://getcrawdad.dev/fleet-install.sh | sh -s -- --uninstall

# Reset (tear down + reinstall fresh)
curl -fsSL https://getcrawdad.dev/fleet-install.sh | sh -s -- --reset

Operator key management

The operator key is shown once during install. If you lose it:

# List operators
cd ~/.crawdad-fleet && docker compose -f docker-compose.fleet.yml \
  exec console crawdad-console operator list

# Reset a key (prints new key once)
cd ~/.crawdad-fleet && docker compose -f docker-compose.fleet.yml \
  exec console crawdad-console operator reset-key --id <operator-id>

# Create a new operator
cd ~/.crawdad-fleet && docker compose -f docker-compose.fleet.yml \
  exec console crawdad-console operator create --name <name>

Prerequisites

The installer checks all of these before touching anything:

Linux or macOS
Docker with Compose v2
curl, openssl, base64, tar
Ports 8800, 9000 free (or set overrides)
≥2 GB disk space

Manual deployment

For custom infrastructure or deploying components separately, see the Console Guide and the full deployment reference (covers manual relay and console setup, including the built-in internal CA).

Console bootstrap flags

Flag	What it does	When to run
`--init-admin`	Generates Ed25519 admin signing identity (key + cert signed by InternalCa)	Once, before first console start
`--init-operator NAME`	Creates the first operator with a random API key. Refuses if operators exist.	Once, after `--init-admin`

Security notes

mTLS everywhere: Set RELAY_REQUIRE_MTLS=true (the default). Running without mTLS is dev-only.
Management token: RELAY_MGMT_TOKEN is generated randomly by init-fleet.sh. Required for the relay’s revocation endpoint.
Admin key protection: The console’s admin signing key is stored encrypted via HardenedStore (systemd-creds or file-backed on Linux, Keychain on macOS). Never stored in plaintext.
InternalCa root key: Stored encrypted in HardenedStore, generated automatically on first console boot. The raw key is never exposed to sidecars — the console uses it server-side to sign device certificates when an enrollment token is redeemed.
Certificate rotation: Device certificates default to 24-hour validity. The sidecar auto-renews via mTLS before expiry.
Hard floors: Data-exfiltration and credential-exposure detection cannot be disabled by any fleet command, even from a valid administrator.