Numbat: Endpoint visibility and control for AI agents

Key Takeaways: Numbat gives you endpoint-level visibility into AI agent activity with local detection, optional pre-action blocking, and forensic reconstruction, all in a single open-source binary.

What is Numbat?

Numbat is an open-source tool that gives you endpoint visibility into AI agent activity, combining local detection, optional pre-action blocking, and forensic reconstruction in one binary. It observes supported desktop, CLI, IDE, and gateway agents through local hooks and plugins, OTLP/HTTP logs, and on-disk session artifacts.

All live and at-rest activity is normalized into a single event model and evaluated by the same CEL rule engine, allowing consistent detection across different agents and surfaces. Detection runs locally on each host, and records can be written to stdout or a local file, with optional delivery over HTTP to your preferred sink.

For the official project, see:

• Numbat on GitHub: https://github.com/perplexityai/numbat
• Numbat documentation (linked from the repo’s docs/ directory)

Core features and capabilities

Live monitoring

Numbat supports live monitoring through hooks, plugins, and OTLP/HTTP log exporters. This lets you see agent activity—tool calls, network requests, file access—in near real time as events flowing through its normalized model.

Endpoint-local detection with rules

Detection is endpoint-local and driven by built-in CEL rules, multi-step sequence rules, and custom YAML rules you can define. You can extend detection by adding your own rules, including complex sequences like “secret read followed by egress” or other risky patterns.

Opt-in blocking

Blocking is opt-in and limited to supported synchronous pre-action hooks. Enforce mode is disabled by default and only applies to rules marked enforce: true, while all shipped rules start monitor-only so you can safely roll out detection.

Forensic reconstruction

Numbat can perform forensic reconstruction from supported on-disk session artifacts, even if the agent was not instrumented with Numbat beforehand. It reads these artifacts in a read-only fashion, reconstructs activity into events and findings, and applies rules without executing commands found in artifacts.

Versioned records and artifact scanning

Events, findings, enforcement decisions, indicators, and scan summaries are output as versioned NDJSON records with JSON Schemas defining the wire format. Read-only artifact scanning includes secret redaction, and normal record output never contains complete raw transcripts unless you explicitly add evidence files to a case bundle.

Inventory and investigation tools

Numbat ships inventory tools for discovering agents, building per-session timelines, and creating portable case bundles with SHA-256 manifests. These bundles help you audit and investigate activity while retaining integrity guarantees.

Single-binary distribution and platforms

Numbat is distributed as a single binary for macOS, Linux, and Windows, built without cgo. That makes deployment simple: you can download the appropriate release for amd64 or arm64, check the provided SHA-256 checksums, and drop the binary onto your endpoints or servers.

If you prefer to build from source, you can do so with Go 1.26.5 or newer using the commands in the quick start.

Installing Numbat

Option 1: Install via go install

If you have Go 1.26.5 or newer, the simplest installation is:

go install github.com/perplexityai/numbat/cmd/numbat@latest

This pulls the latest release and installs the numbat binary into your Go bin directory. Verify installation with:

numbat --help

Option 2: Build a static binary from source

Clone or download the repository, then on macOS or Linux run:

CGO_ENABLED=0 go build -trimpath -o numbat ./cmd/numbat

On Windows PowerShell, use:

$env:CGO_ENABLED = "0"
go build -trimpath -o numbat.exe ./cmd/numbat

These commands compile a static binary without cgo, suitable for deployment across your environment.

Option 3: Use release binaries

The GitHub releases page offers prebuilt binaries for macOS, Linux, and Windows on amd64 and arm64, each with SHA-256 checksums. Download the appropriate asset, verify its checksum, and place it in your PATH or a controlled directory.

Quick start: Inventory and scans

Before installing hooks, you can run read-only commands that do not change agent configuration.

Discover agents

numbat agents

This scans for agents Numbat knows how to parse and reports them for inventory and planning.

Run a full scan

numbat scan

This scans all discovered parser-backed agents and produces NDJSON records of findings and events. If you want to limit discovery to a specific agent, such as Codex, use:

numbat scan --agent codex

These scans are read-only and safe to run on developer workstations, CI hosts, or gateway machines without altering agent settings.

Live monitoring and enforcement

Installing hooks for live capture

For agents with live-capture support, Numbat can install hooks that observe activity in real time. Using Codex as an example:

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

Hooks start in monitor-only mode, and --emit all writes events, findings, indicators, and applicable enforcement decisions to ~/.numbat/records.ndjson.

Hook trust requirements vary by agent and scope, so you should review and trust their current definition in /hooks (CLI) or Settings → Hooks (app), especially after changes like adding --enforce. Managed hooks installed with --managed can be trusted via policy.

Turning monitor rules into enforce rules

All shipped rules are monitor-only by default. To enforce a detection, you copy its complete YAML into a controlled operator directory, keep the same id, add enforce: true, and bump its version. Then you validate and install the effective policy for a supported pre-action hook:

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

This pattern lets you promote rules gradually from monitoring to enforcement, with validation before rollout.

Understanding Numbat output

The README provides example output for three key record types: hook events, sequence findings, and enforcement decisions.

Hook events

Hook events capture live activity, such as an AI agent trying to access cloud metadata endpoints. They include details like actor, endpoint context, event type, project path, source agent, tool name, URL, and tags, all wrapped in a normalized JSON structure.

Sequence findings

Sequence findings represent multi-step detections such as secret-file access followed by data-bearing egress within one session. They cite event IDs, carry severity and rule identifiers, and indicate the observed command and event type.

Enforcement decisions

Enforcement records document decisions like denying a Codex authorized_keys write based on a rule such as persistence.ssh_authorized_keys marked enforce: true. They include decision ids, rule ids and versions, mode (enforce), model, reason, and endpoint context.

Illustrative image suggestion (record structure):

Command overview for daily use

Numbat’s CLI organizes functionality into clear command groups:

• Inventory and investigation: agents, scan, timeline
• Live capture: hook install, hook status, hook uninstall, collect
• Record delivery: ship
• Rule development: rules check, rules list, rules test
• Case bundles: case build, case verify

You can run numbat --help for a full command list or numbat help <command> for detailed flags and exit codes. Commands such as scan, collect, hook EVENT, hook install, and rules check|list|test accept --rules-dir DIR (repeatable) to add operator rules or replace embedded rules by id. To run purely operator-defined rules, use --no-builtin-rules for an operator-only catalog.

Documentation and scope considerations

The docs/ directory in the repository provides deep coverage of:

• Agent coverage and known gaps
• CLI reference (records, sinks, exit codes)
• Live capture setup (hooks and OTLP)
• Deployment patterns (install scope, trust, fleet rollout, output delivery)
• Enforcement semantics and failure behavior
• Rules format, CEL fields, testing, sequences
• Built-in rule catalog
• Record schemas for the wire format

The coverage matrix documents support and gaps per agent, including deferred stores, fidelity limits, and root overrides. Numbat never executes agents or commands found in artifacts and makes outbound requests only to configured HTTP sinks.

At-rest reconstruction is not disk or memory acquisition and cannot recover activity an agent did not persist. Findings are rule matches, not proof of compromise, while case-bundle manifests establish internal consistency without guaranteeing source authenticity for unsigned bundles.

Security model and operational use

Numbat’s records can retain sensitive endpoint and agent context even after redaction. The SECURITY.md file documents the threat model and guidance for private vulnerability reporting.

In practice, you can integrate Numbat into your DevSecOps workflows by:

• Deploying it on developer laptops and workstations running agents like Codex or Claude Code
• Monitoring gateway machines and CI hosts that orchestrate agent workloads
• Building case bundles for security reviews or incident response
• Developing and testing custom rules aligned with your organization’s risk model

Combined with local detection and optional blocking, Numbat becomes a powerful layer of defense and observability for AI agents operating on your endpoints.