opena2a runtime

Agent Runtime Protection (ARP) wrapper for process, network, and filesystem monitoring.

Usage

opena2a runtime <start|status|tail|init> [options]

Subcommands

Subcommand	Description
`init`	Generate an arp.yaml config file for the project.
`start`	Start runtime monitoring with configured monitors.
`status`	Show current monitor status and configuration.
`tail`	View recent runtime events from the event log.

Options

Flag	Description
`--config <path>`	Path to ARP config file (default: arp.yaml).
`--count <n>`	Number of events to show in tail (default: 20).
`--dir <path>`	Target directory.
`--force`	Overwrite existing config (init subcommand only).
`--format <text\|json>`	Output format.

Available Monitors

Monitor	Default	Description
`process`	Enabled	Process monitoring (5s interval)
`network`	Enabled	Network connection monitoring (10s interval)
`filesystem`	Enabled	Filesystem change monitoring
`prompt`	Disabled	AI layer prompt monitoring
`mcp-protocol`	Disabled	MCP protocol interception
`a2a-protocol`	Disabled	A2A protocol interception

Events are logged to .opena2a/arp/events.jsonl in JSONL format.

Examples

# Generate arp.yaml config

opena2a runtime init

# Start monitoring

opena2a runtime start

# View last 50 events

opena2a runtime tail --count 50

What ARP Monitors

Agent Runtime Protection (ARP) provides continuous monitoring of agent execution environments. The three default monitors cover the primary attack surfaces:

Process monitor -- Tracks child process creation, unexpected executables, and suspicious command-line arguments at a configurable interval (default: 5 seconds).
Network monitor -- Logs outbound connections, detects unexpected endpoints, and flags data exfiltration attempts (default: 10 seconds).
Filesystem monitor -- Watches for unauthorized file reads, writes, and deletions in sensitive directories.

The optional prompt, mcp-protocol, and a2a-protocol monitors provide AI-layer visibility when enabled in the configuration.

Config File Format

The arp.yaml file generated by runtime init controls which monitors are active and their parameters:

# arp.yaml
monitors:
  process:
    enabled: true
    interval: 5         # seconds between checks
  network:
    enabled: true
    interval: 10
    allowList:           # trusted endpoints
      - "api.openai.com"
      - "api.anthropic.com"
  filesystem:
    enabled: true
    watchPaths:
      - "./src"
      - "./config"
  prompt:
    enabled: false       # enable for AI-layer monitoring
  mcp-protocol:
    enabled: false
  a2a-protocol:
    enabled: false

events:
  logPath: ".opena2a/arp/events.jsonl"
  maxSizeMb: 50

Expected Output

$ opena2a runtime status

Agent Runtime Protection - Status
==================================
Config:     arp.yaml (loaded)
Log:        .opena2a/arp/events.jsonl (142 events)

Monitors:
  process     ACTIVE   interval=5s   last-check=2s ago
  network     ACTIVE   interval=10s  last-check=4s ago
  filesystem  ACTIVE   watching 2 paths
  prompt      INACTIVE (disabled in config)
  mcp         INACTIVE (disabled in config)
  a2a         INACTIVE (disabled in config)

Error Handling

If no arp.yaml is found, the start and status subcommands print a message suggesting opena2a runtime init to create one. The initsubcommand will not overwrite an existing config unless --force is specified. Thetail subcommand returns an empty result if no events have been recorded yet, rather than raising an error.

guard ARP docs shield