Pilot Api Gateway Manager Setup

Deploy an API gateway management system with 4 agents. Use this skill when: 1. User wants to set up API gateway management with service discovery, routing, a...

Security Scan

The skill's instructions, required binaries, and runtime actions align with its stated purpose of deploying a 4-agent API gateway manager and do not request unrelated credentials or install arbitrary code — but verify the provenance of pilotctl/clawhub and any downstream skills (e.g., slack bridge) before use.

Purpose & Capability

The name/description (API gateway manager with discovery, router, auth, monitor) matches the runtime instructions and required binaries: pilotctl is used for host/handshake/trust commands and clawhub is used to install the role-specific agent 'skills'. All declared requirements (pilotctl, clawhub) are directly used in SKILL.md.

Instruction Scope

Instructions are focused on installing role-specific skills, setting hostnames, writing a manifest under ~/.pilot/setups, and initiating handshakes between peers — all within the stated purpose. One operational detail to note: the SKILL.md states handshakes auto-approve when both sides send a handshake; that behavior could have security implications depending on your network/trust model, so confirm how pilotctl implements handshake/trust before enabling cross-host communications.

Install Mechanism

This is instruction-only (no install spec). The skill expects existing binaries; it does not download or extract code itself. The only installation action is invoking 'clawhub install' which installs other skills — that is expected for this orchestrator-style skill but shifts risk to clawhub and the packages it installs.

Credentials

The skill declares no required environment variables or credentials and the instructions do not read secrets or unrelated env vars. Example payloads include API keys/JWTs for demonstration only; the skill itself does not ask for or persist secrets. Note: some of the child skills (e.g., pilot-slack-bridge) will likely require external tokens — those are outside this skill but worth auditing before use.

Persistence & Privilege

always is false and model invocation is normal. The skill writes a manifest into ~/.pilot/setups (expected for a setup tool) but does not request system-wide config changes beyond its own directory. It does not attempt to modify other skills' configurations.

Assessment

This skill appears consistent with its stated purpose, but take these precautions before installing: 1) Confirm pilotctl and clawhub are legitimate binaries from trusted sources (verify signatures or vendor docs) — the skill relies on them for host/trust operations. 2) Inspect and vet any child skills that clawhub will install (for example pilot-slack-bridge will likely need a Slack token); installing many third-party components increases attack surface. 3) Understand the handshake/trust model: SKILL.md says handshakes auto-approve when both sides send one — ensure you only exchange handshakes with hosts you control or trust, or isolate the deployment network. 4) Review files created under ~/.pilot for sensitive data and set restrictive filesystem permissions. 5) Do not paste real API keys or JWTs into example commands; use sanitized/test data when trying the examples. If you want higher assurance, provide the locations/PKG sources for pilotctl/clawhub and the upstream repositories for the child skills so you can review them before use.

API Gateway Manager Setup

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

Roles

Role	Hostname	Skills	Purpose
discovery	<prefix>-discovery	pilot-discover, pilot-health, pilot-heartbeat-monitor	Registers backends, maintains service registry, health checks
router	<prefix>-router	pilot-load-balancer, pilot-task-router, pilot-metrics	Routes API requests by path, headers, and load
auth	<prefix>-auth	pilot-verify, pilot-audit-log, pilot-blocklist	Validates API keys/JWT, enforces rate limits and quotas
monitor	<prefix>-monitor	pilot-metrics, pilot-alert, pilot-slack-bridge	Tracks latency, error rates, throughput; alerts on anomalies

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.