Quickstart

By the end of this guide you’ll have a Puck agent running on your laptop, registered with your hosted brain, and one completed investigation with a rendered report.

Before you start

A Puck account. Sign up at app.puck.security if you don’t have one yet.
An API key from Console → Settings → API keys. Copy it — you’ll need it in step 2.
macOS (arm64 or amd64) or Linux (amd64). Windows is not yet supported.
Local administrator access to install the binary.

Steps

If you haven’t already, create an account at app.puck.security. After signing in, go to Settings → API keys and create a key. Give it a name like laptop-quickstart so you can revoke it later if needed.

Copy the key — it’s shown only once.

2. Install the agent

The one-liner below downloads the agent binary for your platform, installs it to /usr/local/bin/puck, writes a minimal config file, and registers with your brain.

curl -fsSL https://releases.puck.security/latest/darwin-arm64/install.sh \
  | sudo bash -s -- \
      --brain-url https://brain.puck.security \
      --api-key YOUR_API_KEY

curl -fsSL https://releases.puck.security/latest/darwin-amd64/install.sh \
  | sudo bash -s -- \
      --brain-url https://brain.puck.security \
      --api-key YOUR_API_KEY

curl -fsSL https://releases.puck.security/latest/linux-amd64/install.sh \
  | sudo bash -s -- \
      --brain-url https://brain.puck.security \
      --api-key YOUR_API_KEY

The install script writes ~/.puck/config.json and starts the agent process. You should see puck: connected to brain within a few seconds. For a full walkthrough of the config file and manual install, see Install the agent.

3. Watch the agent register

Open Console → Fleet. Within about 60 seconds your machine should appear with status idle. If it doesn’t appear, check that your API key is valid and that the machine can reach brain.puck.security on port 443.

4. Submit your first investigation

Go to Console → Dashboard and paste the following into the query box:

find any unauthorized AI tools on this machine

Click Investigate. The brain will select your agent as the pathfinder and begin exploring.

You can also trigger an investigation via the API:

curl
Node/TS

curl -X POST https://brain.puck.security/v1/investigations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "find any unauthorized AI tools on this machine"
  }'

const response = await fetch('https://brain.puck.security/v1/investigations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: 'find any unauthorized AI tools on this machine',
  }),
});

const investigation = await response.json();
console.log(investigation.id); // poll GET /v1/investigations/{id} for status

The API returns 202 Accepted immediately. Poll GET /v1/investigations/{id} for status, or open the investigation in the console to watch it live.

5. Watch it run

Click into the investigation from the Console → Dashboard or Investigations list. The detail page streams the pathfinder turns live — you’ll see the brain and agent exchanging messages, the agent reporting what it found, and the brain deciding what to explore next.

The investigation moves through these states: exploring → compiling → executing → analyzing → complete.

6. Read the report

Once the investigation reaches complete (typically 30–90 seconds for a single agent), the report renders inline below the timeline. It leads with the most significant finding, shows per-agent detail, and ends with recommended actions.

Verify it worked

The investigation has status complete in the console and a rendered report is visible below the timeline. If the status is failed, check Console → Activity for the error detail.

Next steps

Install on more agents — run the same install script on more endpoints, or deploy via MDM.
Configure tag policies — apply host-specific behaviour (different severity floors, prompt extensions) by tagging agents on install.
Wire a webhook — get findings pushed to Slack or your SIEM as soon as an investigation completes.