API Gateway Manager Setup

Deploy 4 agents: discovery, router, auth, and monitor.

Roles

Setup Procedure

Step 1: Ask the user which role this agent should play and what prefix to use.

Step 2: Install the skills for the chosen role:

# For discovery:
clawhub install pilot-discover pilot-health pilot-heartbeat-monitor
# For router:
clawhub install pilot-load-balancer pilot-task-router pilot-metrics
# For auth:
clawhub install pilot-verify pilot-audit-log pilot-blocklist
# For monitor:
clawhub install pilot-metrics pilot-alert pilot-slack-bridge

Step 3: Set the hostname:

pilotctl --json set-hostname <prefix>-<role>

Step 4: Write the setup manifest:

mkdir -p ~/.pilot/setups
cat > ~/.pilot/setups/api-gateway-manager.json << 'MANIFEST'
<INSERT ROLE MANIFEST FROM BELOW>
MANIFEST

Step 5: Tell the user to initiate handshakes with direct communication peers.

Manifest Templates Per Role

discovery

{
  "setup": "api-gateway-manager", "setup_name": "API Gateway Manager",
  "role": "discovery", "role_name": "Service Discovery",
  "hostname": "<prefix>-discovery",
  "description": "Registers and discovers backend microservices, maintains service registry, runs health checks.",
  "skills": {"pilot-discover": "Register and discover backend microservice instances.", "pilot-health": "Run periodic health checks against registered backends.", "pilot-heartbeat-monitor": "Detect unresponsive backends via heartbeat timeouts."},
  "peers": [{"role": "router", "hostname": "<prefix>-router", "description": "Receives service registry updates"}, {"role": "monitor", "hostname": "<prefix>-monitor", "description": "Sends health feedback"}],
  "data_flows": [{"direction": "send", "peer": "<prefix>-router", "port": 1002, "topic": "service-registry", "description": "Service registry updates with healthy backends"}, {"direction": "receive", "peer": "<prefix>-monitor", "port": 1002, "topic": "health-feedback", "description": "Health feedback to deregister failing backends"}],
  "handshakes_needed": ["<prefix>-router", "<prefix>-monitor"]
}

router

{
  "setup": "api-gateway-manager", "setup_name": "API Gateway Manager",
  "role": "router", "role_name": "Request Router",
  "hostname": "<prefix>-router",
  "description": "Routes incoming API requests to appropriate backends based on path, headers, and load.",
  "skills": {"pilot-load-balancer": "Distribute requests across healthy backend instances.", "pilot-task-router": "Match request paths and headers to backend services.", "pilot-metrics": "Track routing decisions, request counts, and backend utilization."},
  "peers": [{"role": "discovery", "hostname": "<prefix>-discovery", "description": "Sends service registry updates"}, {"role": "auth", "hostname": "<prefix>-auth", "description": "Receives auth requests"}],
  "data_flows": [{"direction": "receive", "peer": "<prefix>-discovery", "port": 1002, "topic": "service-registry", "description": "Service registry updates with healthy backends"}, {"direction": "send", "peer": "<prefix>-auth", "port": 1002, "topic": "auth-request", "description": "Auth requests for incoming API calls"}],
  "handshakes_needed": ["<prefix>-discovery", "<prefix>-auth"]
}

auth

{
  "setup": "api-gateway-manager", "setup_name": "API Gateway Manager",
  "role": "auth", "role_name": "Auth Gateway",
  "hostname": "<prefix>-auth",
  "description": "Validates API keys and JWT tokens, enforces rate limits and quotas, blocks bad actors.",
  "skills": {"pilot-verify": "Validate API keys and JWT tokens against trusted issuers.", "pilot-audit-log": "Log all access decisions with client metadata for compliance.", "pilot-blocklist": "Maintain and enforce blocklists for abusive clients and IPs."},
  "peers": [{"role": "router", "hostname": "<prefix>-router", "description": "Sends auth requests"}, {"role": "monitor", "hostname": "<prefix>-monitor", "description": "Receives access logs"}],
  "data_flows": [{"direction": "receive", "peer": "<prefix>-router", "port": 1002, "topic": "auth-request", "description": "Auth requests for incoming API calls"}, {"direction": "send", "peer": "<prefix>-monitor", "port": 1002, "topic": "access-log", "description": "Access logs with auth decisions and client metadata"}],
  "handshakes_needed": ["<prefix>-router", "<prefix>-monitor"]
}

monitor

{
  "setup": "api-gateway-manager", "setup_name": "API Gateway Manager",
  "role": "monitor", "role_name": "API Monitor",
  "hostname": "<prefix>-monitor",
  "description": "Tracks latency, error rates, and throughput. Generates dashboards and alerts on anomalies.",
  "skills": {"pilot-metrics": "Compute latency percentiles, error rates, and throughput metrics.", "pilot-alert": "Fire alerts when error rates or latency exceed thresholds.", "pilot-slack-bridge": "Post API health summaries and incident alerts to Slack."},
  "peers": [{"role": "auth", "hostname": "<prefix>-auth", "description": "Sends access logs"}, {"role": "discovery", "hostname": "<prefix>-discovery", "description": "Receives health feedback"}],
  "data_flows": [{"direction": "receive", "peer": "<prefix>-auth", "port": 1002, "topic": "access-log", "description": "Access logs with auth decisions"}, {"direction": "send", "peer": "<prefix>-discovery", "port": 1002, "topic": "health-feedback", "description": "Health feedback to deregister failing backends"}, {"direction": "send", "peer": "external", "port": 443, "topic": "api-alert", "description": "API alerts to ops dashboards and Slack"}],
  "handshakes_needed": ["<prefix>-auth", "<prefix>-discovery"]
}

Data Flows

• discovery -> router : service-registry updates with healthy backends (port 1002)
• router -> auth : auth-request for incoming API calls (port 1002)
• auth -> monitor : access-log with auth decisions and client metadata (port 1002)
• monitor -> discovery : health-feedback to deregister failing backends (port 1002)
• monitor -> external : api-alert via Slack and dashboards (port 443)

Handshakes

# discovery <-> router:
pilotctl --json handshake <prefix>-router "setup: api-gateway-manager"
pilotctl --json handshake <prefix>-discovery "setup: api-gateway-manager"
# router <-> auth:
pilotctl --json handshake <prefix>-auth "setup: api-gateway-manager"
pilotctl --json handshake <prefix>-router "setup: api-gateway-manager"
# auth <-> monitor:
pilotctl --json handshake <prefix>-monitor "setup: api-gateway-manager"
pilotctl --json handshake <prefix>-auth "setup: api-gateway-manager"
# monitor <-> discovery:
pilotctl --json handshake <prefix>-discovery "setup: api-gateway-manager"
pilotctl --json handshake <prefix>-monitor "setup: api-gateway-manager"

Workflow Example

# On discovery -- publish service registry:
pilotctl --json publish <prefix>-router service-registry '{"service":"user-api","instances":[{"host":"10.0.1.5","port":8080,"health":"passing"}]}'
# On router -- publish auth request:
pilotctl --json publish <prefix>-auth auth-request '{"request_id":"req-88210","path":"/api/v2/users","api_key":"key_example_4eC39H"}'
# On auth -- publish access log:
pilotctl --json publish <prefix>-monitor access-log '{"request_id":"req-88210","client":"acme-corp","decision":"allow","latency_ms":12}'
# On monitor -- publish health feedback:
pilotctl --json publish <prefix>-discovery health-feedback '{"service":"user-api","instance":"10.0.1.6:8080","status":"failing","error_rate":0.42}'

Dependencies

Requires pilot-protocol skill, pilotctl binary, clawhub binary, and a running daemon.