FAQ

Answers to the questions we hear most often. If yours isn’t here, email us or open a discussion on GitHub.

Read-only by design

Does Puck modify anything on the endpoint?

No. The agent is strictly read-only. It executes only whitelisted, read-only system commands (things like ps, lsof, find, cat, launchctl, systemctl). Every command string is validated against a per-OS allowlist before execution. Commands like rm, mv, chmod, curl, and any interpreter (python, node, bash -c) are unconditionally blocked and can never be executed, regardless of what a plan says.

Can Puck remediate findings?

No. Puck is an investigation tool, not a remediation tool. It finds things and reports them. It never writes to the filesystem (except its own log file and local cache directory), never modifies process state, never changes network configuration, and never executes arbitrary code. The read-only constraint is a security invariant, not a product decision — it is enforced at the command-validation layer, not just the prompt.

Does Puck use a kernel driver or kernel extension?

No. The agent is a single userspace binary. It spawns whitelisted system subprocesses to collect information, the same way a security analyst would run commands manually. There is no kext, no eBPF program, no kernel module, and no requirement for SIP-disabled mode on macOS.

What commands does the agent actually run?

On macOS and Linux the allowed set covers: ps, pgrep, lsof, ss, netstat, find, cat, head, tail, ls, stat, file, shasum/sha256sum, mount, df, launchctl (macOS), systemctl (Linux), crontab, defaults (macOS), dscl (macOS), id, who, last, plutil (macOS), csrutil (macOS), spctl (macOS), docker ps/inspect/images (read-only), grep, awk, sed, xattr (macOS), getfattr (Linux), mdls (macOS), and the cloud CLIs (aws, gcloud, kubectl) when enabled by tag policy. The full list is version-controlled in the agent source — see agent/internal/whitelist/.

Privacy & data handling

What data leaves the endpoint?

Only the output of whitelisted commands — process names, file paths, port numbers, installed software lists, scheduled job definitions, and similar system metadata. The agent never reads home directory contents by default. File contents are only read when a plan explicitly requests a specific file path, and the content is sanitized before it reaches any LLM.

Where is the data stored?

In the hosted version, findings, investigation narratives, and agent metadata are stored in Puck’s Postgres database, scoped to your account. No cross-tenant data access is possible. Retention periods are configurable per account.

Does Puck read home directories or personal files?

Not by default. Plans can include find or cat steps targeting specific paths (for example, to check a suspicious file that a prior step located). Every such step goes through the command whitelist. Plans that attempt to read broad home-directory globs are rejected at the validation layer. If you want to exclude specific paths, set the exclusions list in the agent config.

Is data sent to third-party services?

The brain sends sanitized investigation context to LLM providers (Anthropic by default, optionally OpenAI). Raw file contents are never sent to an LLM — they go through an input sanitizer that strips personal data patterns before inclusion in any prompt. LLM providers do not receive identifying information about the endpoints being investigated.

LLM use

Which LLM providers does Puck use?

Anthropic (Claude) is the primary provider. OpenAI is available as a secondary option. Ollama support is included for on-premises deployments. The LLM provider is configured per-account and can be changed without agent redeployment.

What gets sent to the LLM?

Investigation context: the NL query, anonymized summaries of agent findings, and the pathfinder conversation transcript. Raw file contents and command output go through a sanitizer that strips patterns that look like credentials, PII, or prompt-injection payloads before any text reaches an LLM prompt. The console never surfaces raw file contents — only findings, summaries, and reasoning chains.

Can a malicious file on an endpoint inject instructions into the LLM?

Puck includes a prompt-injection sanitizer that processes all untrusted content (file contents, command output) before it enters any LLM prompt. The sanitizer is a hard architectural requirement — the brain will not forward unsanitized endpoint data to any LLM. That said, no sanitizer is perfect: defense in depth assumes that an attacker may partially succeed at injection and limits the blast radius by constraining what any single LLM call can act on.

Operational

What happens if the brain goes offline?

The agent polls the brain periodically (heartbeat every 60 seconds, plan poll every 10 seconds during active investigations, every 60 seconds otherwise). If the brain is unreachable, the agent retries with exponential backoff and continues to run any in-progress plan steps it already has. No data is lost locally — the agent buffers results and ships them when the brain reconnects. If the brain is offline long enough that heartbeat lapse triggers an agent.disconnected webhook, the agent will re-register automatically on reconnection.

Does the agent self-update?

No. The agent binary does not update itself. Upgrades are performed by replacing the binary (via MDM, Ansible, package manager, or manual deployment) and restarting the service. The brain communicates the minimum supported agent version; agents below the minimum are rejected at the heartbeat endpoint with a 426 Upgrade Required response.

What is the upgrade path?

Download the new binary from the releases page.
Verify the checksum.
Replace the binary on disk.
Restart the service (systemctl restart puck / launchctl kickstart -k system/com.puck.agent).

Rolling upgrades across a fleet can be automated with any configuration management tool. The agent is stateless with respect to upgrades — no migration steps are required.

Pricing & limits

Are there limits on the number of agents?

The hosted (Pro) plan is billed per connected agent. The limit is enforced at the heartbeat endpoint — agents above your account’s cap receive 402 Payment Required and will not be assigned investigations until capacity is available. Contact us to raise your cap.

Is there a cost per investigation?

Investigations consume LLM tokens and are billed as part of your plan. The exact model tier used (and therefore the token cost) depends on the complexity of the investigation — haiku-class for light triage, sonnet-class for standard investigations, opus-class for deep chains. Your account dashboard shows cumulative usage.

Can I cap the number of investigations per day?

Yes. Set max_investigations_per_day on a tag policy to budget investigation depth for specific agent groups. Investigations that exceed the cap are queued until the next day.