Docs/Agent Simulators

Agent Simulators

SatGate includes built-in simulators for each enforcement mode. These run real agent flows through your configured gateway — no external tools needed.

How simulators work: Each simulator sends real authenticated requests through your SatGate instance. Events appear in your activity feed just like production traffic. Use them to validate your configuration before connecting real agents.

Observe Simulator

Tests shadow monitoring — the foundation of SatGate's visibility layer.

What it tests

  • Agent authenticates with a macaroon token
  • Agent makes API/tool calls through the gateway
  • All events are logged to the activity feed
  • Cascade kill switch — revoking a parent token terminates all child sessions

How to use it

  1. Open the Observe Simulator in the dashboard
  2. Click "Run" to start the simulation
  3. Watch the activity feed — you'll see authentication events, tool calls, and cost tracking in real time
  4. Test the kill switch by revoking the simulated agent mid-session

What to look for

  • Events appear in the feed within seconds
  • Tool calls show correct cost attribution
  • Kill switch terminates all child sessions, not just the parent

Control Simulator

Tests budget enforcement and delegation controls across three scenarios.

Scenario 1: Admin Kill Switch

An agent authenticates and starts making calls. Mid-session, the admin revokes its token. The agent receives a 401 Unauthorized on the next request and is immediately cut off.

Scenario 2: Economic Firewall

An agent is given a budget ceiling. It makes tool calls that consume credits. When the budget is exhausted, the agent receives 402 Payment Required — the economic firewall kicks in.

Scenario 3: Agent Swarm

A parent agent delegates tokens to child agents (an "agent swarm"). Revoking the parent's token cascades to all children — every agent in the swarm is terminated simultaneously.

How to use it

  1. Open the Control Simulator in the dashboard
  2. Select a scenario or run all three
  3. Click "Run" and watch the activity feed
  4. Observe the enforcement responses (401s, 402s) as they happen

What to look for

  • Kill switch produces immediate 401, not a delayed response
  • Budget exhaustion triggers 402 at exactly the configured ceiling
  • Cascade revocation terminates all child tokens in the swarm

Charge Simulator

Tests the full L402 payment flow — the protocol that lets agents pay for API access with Lightning micropayments.

What it tests

The complete L402 handshake:

  1. Agent calls an API endpoint
  2. SatGate responds with 402 Payment Required + a Lightning invoice
  3. Agent pays the invoice
  4. Agent retries the request with proof of payment
  5. SatGate validates payment and returns 200 OK

How to use it

  1. Open the Charge Simulator in the dashboard
  2. Click "Run" to start the L402 flow
  3. Watch each step of the handshake in the activity feed
  4. The simulator handles payment automatically — no real sats required

What to look for

  • Initial 402 includes a valid Lightning invoice in the response
  • Payment confirmation is near-instant
  • The retry with payment proof returns 200 with the expected data
  • All events (challenge, payment, fulfillment) appear in the activity feed

Related