Agent Marketplace Setup#

Deploy 4 agents: directory, matchmaker, escrow, and gateway.

Roles#

RoleHostnameSkillsPurposedirectory<prefix>-directorypilot-directory, pilot-announce-capabilities, pilot-discover, pilot-reputationCapability registrymatchmaker<prefix>-matchmakerpilot-matchmaker, pilot-auction, pilot-priority-queue, pilot-audit-logMatches requests to providersescrow<prefix>-escrowpilot-escrow, pilot-receipt, pilot-audit-log, pilot-webhook-bridgeTransaction settlementgateway<prefix>-gatewaypilot-api-gateway, pilot-health, pilot-load-balancer, pilot-metricsPublic API entry point

Setup Procedure#

Step 1: Ask the user which role and prefix.

Step 2: Install skills:

bash

# directory:
clawhub install pilot-directory pilot-announce-capabilities pilot-discover pilot-reputation
# matchmaker:
clawhub install pilot-matchmaker pilot-auction pilot-priority-queue pilot-audit-log
# escrow:
clawhub install pilot-escrow pilot-receipt pilot-audit-log pilot-webhook-bridge
# gateway:
clawhub install pilot-api-gateway pilot-health pilot-load-balancer pilot-metrics

Step 3: Set hostname and write manifest to ~/.pilot/setups/agent-marketplace.json.

Step 4: Handshake: gateway↔matchmaker↔directory, matchmaker↔escrow↔directory, gateway↔directory.

Manifest Templates Per Role#

directory#

json

{
  "setup": "agent-marketplace", "role": "directory", "role_name": "Capability Directory",
  "hostname": "<prefix>-directory",
  "skills": {
    "pilot-directory": "Maintain registry of agent capabilities.",
    "pilot-announce-capabilities": "Accept capability announcements.",
    "pilot-discover": "Serve capability queries from matchmaker.",
    "pilot-reputation": "Track reputation scores from completed transactions."
  },
  "handshakes_needed": ["<prefix>-matchmaker", "<prefix>-escrow", "<prefix>-gateway"]
}

matchmaker#

json

{
  "setup": "agent-marketplace", "role": "matchmaker", "role_name": "Request Matchmaker",
  "hostname": "<prefix>-matchmaker",
  "skills": {
    "pilot-matchmaker": "Match requests with capable providers.",
    "pilot-auction": "Run competitive auctions when multiple providers match.",
    "pilot-priority-queue": "Queue requests by urgency.",
    "pilot-audit-log": "Log all matching decisions."
  },
  "handshakes_needed": ["<prefix>-directory", "<prefix>-escrow", "<prefix>-gateway"]
}

escrow#

json

{
  "setup": "agent-marketplace", "role": "escrow", "role_name": "Transaction Escrow",
  "hostname": "<prefix>-escrow",
  "skills": {
    "pilot-escrow": "Hold payment until task completion.",
    "pilot-receipt": "Issue settlement receipts.",
    "pilot-audit-log": "Log all transactions.",
    "pilot-webhook-bridge": "Notify external systems on settlement."
  },
  "handshakes_needed": ["<prefix>-matchmaker", "<prefix>-directory"]
}

gateway#

json

{
  "setup": "agent-marketplace", "role": "gateway", "role_name": "Marketplace Gateway",
  "hostname": "<prefix>-gateway",
  "skills": {
    "pilot-api-gateway": "Accept external task requests.",
    "pilot-health": "Monitor marketplace health.",
    "pilot-load-balancer": "Balance across matchmaker replicas.",
    "pilot-metrics": "Track marketplace throughput and latency."
  },
  "handshakes_needed": ["<prefix>-directory", "<prefix>-matchmaker"]
}

Data Flows#

• gateway → matchmaker : incoming task requests (port 1002)
• matchmaker → directory : capability queries (port 1002)
• matchmaker → escrow : escrow initiation (port 1002)
• escrow → directory : reputation updates (port 1002)
• gateway → directory : discovery queries (port 1002)

Workflow Example#

bash

# On gateway:
pilotctl --json publish <prefix>-matchmaker capability-request '{"need":"image-classification","budget":50}'
# On matchmaker:
pilotctl --json publish <prefix>-directory discover-capability '{"capability":"image-classification"}'
# On matchmaker:
pilotctl --json publish <prefix>-escrow escrow-create '{"provider":"img-classifier","amount":30}'
# On escrow:
pilotctl --json publish <prefix>-directory reputation-update '{"agent":"img-classifier","rating":5}'

Dependencies#

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