Superagent runs its monitoring engine on each endpoint. Events are normalized and evaluated locally. By default, only findings, enforcement decisions, and client health are delivered to Superagent; the full normalized event stream stays on the endpoint.

This feature is separate from Agent reports, which perform black-box adversarial tests against a deployed AI system.

Register and pair a client

Organization owners can register clients.

1. Open Agents at /app/agents.
2. Select Register client and give the installation a recognizable name.
3. Copy the one-time pairing command. The token expires after 15 minutes and is consumed by the first successful pairing.
4. Run the command on the local workstation, cloud runner, or agent host.

curl -fsSL https://superagent.sh/install.sh | sh -s -- connect \
  --client-id CLIENT_ID \
  --pairing-token ONE_TIME_TOKEN \
  --api-url https://superagent.sh

The installer downloads the standalone executable for the current platform from the latest GitHub Release, verifies its SHA-256 checksum, and installs it to ~/.local/bin without sudo. It then passes the remaining arguments to the installed superagent executable. Node.js, npm, and npx are not required.

The pairing token is exchanged for a revocable client credential. Superagent stores only credential hashes. The CLI stores the plaintext credential in its local configuration with owner-only file permissions. The same command syncs the effective rules, installs Claude monitoring, and starts a detached record shipper. No additional setup command is required.

Claude is the safe default. To monitor another supported agent, add --agent NAME, for example:

curl -fsSL https://superagent.sh/install.sh | sh -s -- connect \
  --client-id CLIENT_ID \
  --pairing-token ONE_TIME_TOKEN \
  --api-url https://superagent.sh \
  --agent cursor

For self-hosted deployments, pass the control-plane origin:

curl -fsSL https://superagent.example.com/install.sh | sh -s -- connect \
  --client-id CLIENT_ID \
  --pairing-token ONE_TIME_TOKEN \
  --api-url https://superagent.example.com

Groups and effective rules

A client can belong to multiple groups. Its effective rule catalog is the deterministic union of rules assigned to those groups.

Rule IDs are unique within an organization. Assigning the same rule to multiple groups does not duplicate it. A custom rule with the same ID as a built-in rule replaces that built-in rule.

Use the Groups tab to create groups and the client table to manage membership. Use the Rules tab to write YAML security rules and assign them to groups.

id: acme.secrets.env_read
version: "1.0"
title: Environment file read
severity: high
expr: |-
  event.event_type == "file.read" &&
  event.file_path.matches("(^|/)\\.env$")

Superagent validates the YAML structure when it is saved. The endpoint performs authoritative rule validation before activation. Invalid updates are rejected locally and the last known-good catalog remains active.

See Creating rules for the rule assistant, YAML schema, sequence rules, and enforcement behavior.

Programmatic management

Organization API keys can manage clients, groups, rules, pairing tokens, and alerts through the REST API or MCP. See the Agents API for endpoints and examples.

Review activity and alerts

The Logs tab in Agents shows a live, bounded view of recent endpoint activity. Use it for current monitoring and connection diagnostics; it is not the durable alert inbox.

Durable rule findings and enforcement decisions appear in Notifications. Select the Agent monitoring filter to review them across pages. A blocked action produces one notification that unifies the finding and enforcement decision instead of separate finding and deny notifications.

Organization webhooks can send the same durable alerts to external systems. Subscribe to agent.finding_created for detections and agent.action_blocked for denied actions from Settings → Webhooks. See Webhooks for payloads, signatures, and retries.

Notification details show only the redacted evidence included in a finding or enforcement decision. Superagent does not upload or expose the full normalized endpoint event stream.

Manage live monitoring

The pairing command installs and starts live Claude monitoring automatically. Check both the hook and background shipper:

superagent monitor status --agent claude

The CLI writes findings and enforcement decisions to ~/.config/superagent/records.ndjson. The detached shipper checkpoints acknowledged offsets, retries failed delivery with exponential backoff, sends a heartbeat, and polls Superagent for rule updates. Its PID state and log are private files in the same Superagent configuration directory.

Start or stop background shipping explicitly with:

superagent monitor start
superagent monitor stop

superagent monitor start is idempotent: it reports an already-running shipper instead of starting a duplicate, and replaces stale PID state. To run shipping in the foreground under your own process manager, keep using:

superagent monitor ship

For a manual agent override after connecting, install that agent's hooks and ensure the shipper is running:

superagent monitor install --agent codex
superagent monitor start

Remove hooks with superagent monitor uninstall --agent codex. Stopping the shipper is separate because another installed agent may still be writing records.

Monitor and enforce modes

Monitoring is the default. Enforcement requires two explicit choices:

1. The YAML rule must contain enforce: true.
2. The endpoint hook must be installed with --enforce.

superagent monitor install --agent codex --enforce

This preserves fail-safe behavior: marking a rule as enforce-eligible in the UI does not silently enable blocking on an endpoint.

Scan existing artifacts

Read-only scans use the same effective rule catalog:

superagent scan
superagent scan --agent codex

Supported platforms

The standalone superagent executable contains the pinned Numbat engine and supports:

• macOS arm64 and x64
• Linux arm64 and x64

Release assets are named superagent-<os>-<arch>. The release pipeline publishes SHA-256 checksums, signs the checksum manifest, and signs and notarizes macOS executables. Windows and managed fleet/MDM deployment are not included in the initial release.

Revocation and local cleanup

Use Revoke on the client in the Agents UI to invalidate all of its credentials immediately. Creating a new pairing token does not by itself revoke an active credential; completing the new pairing rotates the credential.

superagent disconnect removes local credentials and synced rules. It does not revoke the server credential, so revoke the client in the UI when decommissioning an endpoint.