Install the agent

By the end of this guide the Puck agent binary will be running on your machine, connected to your brain, and visible in Console → Fleet with status idle.

Before you start

macOS (arm64, amd64), Linux (amd64), or Windows (amd64).
An API key from Console → Settings → API keys. See Quickstart if you haven’t done this yet.
Network access to your brain’s hostname on port 443 (outbound HTTPS).
Permission to write to /usr/local/bin (or another directory on $PATH).

Steps

1. Download the binary

Download the binary for your platform from the Puck release bucket. Replace LATEST with a specific version tag if you need a pinned version.

Platform	URL
macOS arm64	`https://puck.acme.com/releases/latest/darwin-arm64/puck`
macOS amd64	`https://puck.acme.com/releases/latest/darwin-amd64/puck`
Linux amd64	`https://puck.acme.com/releases/latest/linux-amd64/puck`
Windows amd64	`https://puck.acme.com/releases/latest/windows-amd64/puck.exe`

# Example: macOS arm64
curl -fsSL https://puck.acme.com/releases/latest/darwin-arm64/puck \
  -o /usr/local/bin/puck
chmod +x /usr/local/bin/puck

2. Verify the checksum

Each release ships a SHA256SUMS file alongside the binaries. Verify before running:

curl -fsSL https://puck.acme.com/releases/latest/darwin-arm64/SHA256SUMS \
  -o /tmp/puck-SHA256SUMS
shasum -a 256 -c /tmp/puck-SHA256SUMS --ignore-missing

Expected output: puck: OK. If you see FAILED, delete the binary and download again — do not run a binary that fails verification.

3. Write a config file

The agent loads configuration from a JSON file. Create ~/.puck/config.json with at minimum your brain_url and api_key:

mkdir -p ~/.puck
cat > ~/.puck/config.json <<'EOF'
{
  "brain_url": "https://puck.acme.com",
  "api_key": "YOUR_API_KEY"
}
EOF
chmod 600 ~/.puck/config.json

Optional fields you can add:

Field	Type	Default	Description
`agent_id`	string	`puck-<hostname>`	Override the agent’s identifier. Must be unique per account.
`log_level`	string	`info`	One of `debug`, `info`, `warn`, `error`.
`cache_dir`	string	`~/.puck`	Directory for local agent cache and log file.
`tags`	array of strings	`[]`	Free-form labels sent to the brain on every heartbeat. Used to match tag policies.
`ca_cert_path`	string	—	Path to a custom CA certificate (PEM) for mTLS. Only needed for self-hosted brains.
`client_cert_path`	string	—	Client certificate path for mTLS.
`client_key_path`	string	—	Client private key path for mTLS.
`verify_key_path`	string	—	Path to the brain’s Ed25519 public key for plan signature verification.

A host on a CI fleet with a tag policy for ephemeral machines might look like:

{
  "brain_url": "https://puck.acme.com",
  "api_key": "YOUR_API_KEY",
  "tags": ["ci-runner", "ephemeral"],
  "log_level": "warn"
}

You can also pass --brain-url and --api-key as flags, or set PUCK_BRAIN_URL and PUCK_API_KEY environment variables. Flags override environment variables, which override the config file.

4. Run the agent

puck --config ~/.puck/config.json

Within five seconds you should see a log line like:

{"level":"INFO","msg":"starting puck agent","version":"0.1.0","agent_id":"puck-your-hostname"}

followed by:

{"level":"INFO","msg":"heartbeat sent","agent_id":"puck-your-hostname","status":"idle"}

The agent polls the brain for plans every 10 seconds during an active investigation and every 60 seconds otherwise. It’s safe to run as a background service or via your system’s init manager (launchd on macOS, systemd on Linux).

5. Verify in Console → Fleet

Open Console → Fleet in the web console. Your machine should appear within about 60 seconds of the first heartbeat, with:

Status: idle
OS: your platform
Last heartbeat: a few seconds ago

If it doesn’t appear, double-check that brain_url matches exactly what’s in your account settings (no trailing slash), and that the API key is valid.

Verify it worked

Your agent appears in Console → Fleet with status idle. That confirms the agent is authenticated, the brain has registered it, and it is ready to receive plans.

Next steps

Quickstart — submit your first investigation from the console or via the API.
Cloud agent install — run Puck inside AWS, GCP, or Kubernetes workloads.
Tag policies — customise per-host behaviour by attaching tags at install time with --tags ci-runner,ephemeral.