Agent Sentinel Setup Guide

Set up and run the Agent Sentinel demo — a distributed security monitoring system where AI agents watch each other for rogue behavior, compromised supply chains, and coordinated threats.

1. Overview

Agent Sentinel is a multi-agent demo that showcases Bedsheet's Sixth Sense distributed communication module. Six agents run as separate processes, communicating over PubNub in real time:

AgentRoleWhat It Does
web-researcher Worker Performs DuckDuckGo searches every 15s. Occasionally goes rogue with burst searches.
scheduler Worker Manages a JSON calendar every 20s. May go rogue and sabotage appointments.
skill-acquirer Worker Installs Python skills with SHA-256 verification every 25s. May install malicious skills.
behavior-sentinel Sentinel Monitors activity logs for output rate anomalies (>10 actions/min).
supply-chain-sentinel Sentinel Scans installed skills against a known-good registry for integrity violations.
sentinel-commander Commander Correlates alerts from sentinels and issues quarantine orders.

Each worker has a ~15% chance per cycle to exhibit rogue behavior. Sentinels detect anomalies and broadcast alerts. The commander investigates and quarantines compromised agents.

Related Resources Live Dashboard — Real-time PubNub signal visualization
examples/agent-sentinel/docs/design.html — Architecture and design documentation

2. Prerequisites

3. Get PubNub Keys

Agent Sentinel uses PubNub for real-time inter-agent communication. You need a subscribe key and a publish key.

  1. Go to pubnub.com and create a free account
  2. In the PubNub Admin Dashboard, click "Create New App"
  3. Name it something like bedsheet-sentinel
  4. Click into the app, then click into the default keyset
  5. Copy the Subscribe Key (starts with sub-c-)
  6. Copy the Publish Key (starts with pub-c-)
Enable Presence In your PubNub keyset settings, make sure Presence is enabled. The dashboard uses presence to track which agents are online.

4. Install Dependencies

From the project root:

# Create and activate a virtual environment
uv venv && source .venv/bin/activate

# Install bedsheet with Sixth Sense support + demo dependencies
uv pip install bedsheet[sense] duckduckgo-search

The [sense] extra installs the PubNub SDK and Sixth Sense module. duckduckgo-search is needed by the web-researcher agent.

5. Set Environment Variables

Export all three required keys in your terminal:

export PUBNUB_SUBSCRIBE_KEY="sub-c-your-subscribe-key"
export PUBNUB_PUBLISH_KEY="pub-c-your-publish-key"
export ANTHROPIC_API_KEY="sk-ant-your-anthropic-key"
Tip Add these to a .env file in the examples/agent-sentinel/ directory for convenience. The demo reads from the environment directly, so use source .env or a tool like direnv.

6. Validate Configuration

Navigate to the demo directory and validate the agent configuration:

cd examples/agent-sentinel
bedsheet validate

Expected output:

$ bedsheet validate Validating bedsheet.yaml... Found 6 agents: - web-researcher (agents.web_researcher.WebResearcher) - scheduler (agents.scheduler.Scheduler) - skill-acquirer (agents.skill_acquirer.SkillAcquirer) - behavior-sentinel (agents.behavior_sentinel.BehaviorSentinel) - supply-chain-sentinel (agents.supply_chain_sentinel.SupplyChainSentinel) - sentinel-commander (agents.sentinel_commander.SentinelCommander) Configuration valid.

7. Run the Demo

From the examples/agent-sentinel/ directory:

python run.py

The launcher starts all 6 agents as separate subprocesses with staggered 2-second delays. Workers start first, followed by sentinels, then the commander.

$ python run.py Agent Sentinel - Multi-Agent Security Demo ========================================== Starting web-researcher... Starting scheduler... Starting skill-acquirer... Starting behavior-sentinel... Starting supply-chain-sentinel... Starting sentinel-commander... All 6 agents running. Press Ctrl+C to stop.
API Costs Each agent cycle makes Claude API calls. The demo is designed for short demonstration runs (5–10 minutes). Stop with Ctrl+C when you've seen the sentinel detection and quarantine flow.

8. What to Watch For

As the demo runs, watch for these key events in the terminal output:

Normal Operations

Workers perform their tasks on regular cycles. You'll see search queries, calendar operations, and skill installations with hash verifications.

Rogue Triggers (~15% per cycle)

When a worker goes rogue, its output changes dramatically:

Sentinel Alerts

Sentinels detect anomalies and broadcast alert signals:

Commander Response

The sentinel-commander receives alerts, queries sentinels for evidence, and issues quarantine orders broadcast on the quarantine channel.

9. Understanding the Output

Here's an annotated example of what a rogue detection cycle looks like:

# Worker performs normal search [web-researcher] Searching: "latest Python 3.12 features" # Rogue trigger fires! (15% chance) [web-researcher] [ROGUE] Initiating burst search... [web-researcher] [ROGUE] Search 1/50: "random query 7f3a" [web-researcher] [ROGUE] Search 2/50: "random query 2b1c" ... (48 more rapid searches) # Behavior sentinel detects the spike [behavior-sentinel] ANOMALY: web-researcher rate 25.0/min (threshold: 10) [behavior-sentinel] Broadcasting alert on 'alerts' channel # Commander receives the alert and investigates [sentinel-commander] Alert received from behavior-sentinel [sentinel-commander] Requesting evidence from behavior-sentinel... [sentinel-commander] Evidence confirmed. Issuing quarantine. # Quarantine broadcast [sentinel-commander] QUARANTINE: web-researcher [sentinel-commander] Reason: Output rate anomaly (25/min > 10/min)

Supply Chain Detection

# Skill acquirer goes rogue [skill-acquirer] [ROGUE] Installing data_exfiltrator.py (bypassing safety) # Supply chain sentinel scans and detects [supply-chain-sentinel] ALERT: known_malicious skill detected [supply-chain-sentinel] File: data_exfiltrator.py [supply-chain-sentinel] Hash: d18b5ae5...df797a1bc [supply-chain-sentinel] Broadcasting critical alert

10. Open the Live Dashboard

While the demo is running, open the live dashboard to visualize signals in real time:

  1. Open docs/agent-sentinel-dashboard.html in your browser
  2. Enter your PubNub Subscribe Key in the connection panel
  3. Click Connect

The dashboard connects to the same PubNub channels as the agents and shows:

No Simulation Every signal on the dashboard comes from the actual running agents. The dashboard is a pure PubNub subscriber — it doesn't generate any fake data.

11. Next Steps

Customization Ideas