Skip to content
Puck Docs

What is Puck?

Puck puts a curious little red teamer on every endpoint. The agent is read-only — it explores its host the way an attacker would (reading files, following threads, inspecting processes) but can’t write anything.

Puck ships in two distributions:

  • OSS (puck-oss) — an MCP server your AI client (Claude Code, Cursor, any MCP-spec client) uses to investigate endpoints. The MCP server validates every command against a typed allowlist; the Rust agent validates it again before execution. No central brain, no fleet coordination — one investigation at a time, driven by your AI surface.
  • Enterprise — adds a server-side brain that runs multi-turn LLM exploration, fans out Ed25519-signed plans across the fleet, correlates findings into a blast-radius map, and compiles confirmed chains into calibrated detection. The hive mind ties it together — what one Puck finds, every Puck knows.

The rest of this page describes the Enterprise-shaped product. OSS is a strict subset (no brain, no pathfinder service, no hive mind, no calibrated-detection compiler).

Why it exists

Endpoint security tools spend most of their time watching what already happened. They wait for an event — a process launch, a file write, a network connection — and alert when it matches a known bad pattern. That model is reactive by design, and it has a ceiling: you can only detect what you already know to look for.

Puck takes the opposite approach. Instead of waiting, it goes looking. An agent on a macOS developer laptop will read the browser extension list, check which processes have open network connections, enumerate scheduled tasks, and follow any thread that looks out of place — all without being told to, and without ever touching a kernel driver. Because every agent shares its discoveries with the brain, a suspicious process name found on one host becomes a fleet-wide lead within seconds.

This matters most in three situations:

  1. An analyst suspects compromise and wants to know fast. Traditional tooling surfaces what triggered an alert. Puck surfaces what the attacker touched, where they went next, and whether any other host shows the same pattern.
  2. No one has asked a specific question yet. Puck runs ambient investigations in the background, surfacing anomalies before anyone knew to look.
  3. A finding has been confirmed and needs to become a repeatable check. Puck can graduate a one-off discovery into a deterministic check that runs on every new agent that joins the fleet.

How it works

Every Puck agent operates in three tiers of autonomy, depending on how much local reasoning is required:

  • Tier 1 — Scripted. The brain compiles a plan: a list of read-only commands the agent executes in order. The agent collects results and ships them back.
  • Tier 2 — Reactive branching. The plan includes conditional logic. If a particular file exists, follow one path; if not, follow another. The agent evaluates branches locally with no round-trip to the brain.
  • Tier 3 — Call-home. The agent hits something it cannot classify locally — an unexpected process, an unknown binary, a configuration that doesn’t match any baseline. It packages the context and escalates to the brain, which opens a multi-turn conversation with that specific agent to decide what to investigate next.

Plans originate from pathfinder agents: one agent per OS that the brain runs a full multi-turn LLM conversation with before the fleet-wide plan is compiled. The pathfinder’s job is to explore deeply, reason about what it finds, and tell the brain what the rest of the fleet should look for. That exploration is what makes Puck’s plans threat-informed rather than templated.

The hive mind ties it together. When any agent produces a high-confidence finding, the brain correlates it against what every other agent is seeing. If the correlation looks meaningful, it generates a lead — a short targeted plan — and pushes it to the agents most likely to have matching artifacts. One discovery becomes a fleet-wide sweep in seconds, without the analyst having to ask.

All of this is read-only. Puck never writes to the filesystem (beyond its own log), never modifies configuration, never remediates anything, and never installs a kernel driver. Collection happens entirely through a strict whitelist of read-only system commands — ps, lsof, find, cat, stat, and their equivalents — all spawned as subprocesses with enforced timeouts.

When you’d touch it

Most of the time you won’t need to think about Puck’s internals. The three moments where it matters are:

  • Incident fleet query. You suspect a host is compromised, or you’ve received a threat intel report and want to know if your fleet is exposed. Go to Console → Dashboard, paste a plain-English question, and submit. Puck selects a pathfinder, explores the question, compiles a plan, runs it across your fleet, and renders a narrative report — usually in 30–90 seconds.

  • Ambient curiosity. Puck runs background investigations on a schedule without operator prompting. You configure what categories of questions to keep asking, and the brain surfaces anything that looks out of place. This is the mode that catches things no one thought to query.

  • Calibrated detection. When a finding from any investigation is valuable enough to monitor continuously, you can compile it into a deterministic check that runs on every connected agent. Calibrated detections don’t require LLM reasoning each time — they’re compiled into lightweight plans the agent can execute autonomously. (The wire event for promotion is still check.graduated — see webhooks.)

  • Quickstart — have a Puck agent running and your first investigation complete in five minutes.
  • Install the agent — binary download, config file, and first heartbeat.
  • Concepts: Investigations — investigation states, scope, and what a completed investigation produces.