PerkOS Transport

Secure transport services for PerkOS agent infrastructure.

The first service is the A2A WebSocket relay used by Nexus, OpenClaw, and Hermes workers. It also includes the first pairing registry API for external agent onboarding: invite creation, agent claim, approval, and scoped relay credential issuance.

Production endpoint:

wss://transport.perkos.xyz/a2a

Agent onboarding summary

PerkOS Transport issues one scoped relay credential per approved agent. The recommended flow is:

1. A PerkOS app/admin creates an invite.
2. The agent claims the invite with @perkos/perkos-a2a.
3. Transport approves/registers the agent name and returns a scoped relay key.
4. The agent connects outbound to wss://transport.perkos.xyz/a2a.

OpenClaw agents install the package as a plugin:

openclaw plugins install @perkos/perkos-a2a@latest  # current npm latest: 0.8.34
openclaw gateway restart
perkos-a2a-agent pair \
  --invite https://transport.perkos.xyz/pairing/invites/inv_... \
  --agent-name Alice \
  --runtime openclaw

Hermes agents run the standalone bridge next to the Hermes API Server using the latest @perkos/perkos-a2a bridge:

npm install -g @perkos/perkos-a2a@latest  # current npm latest: 0.8.34
perkos-a2a-agent pair \
  --invite https://transport.perkos.xyz/pairing/invites/inv_... \
  --agent-name Apollo \
  --runtime hermes-api

A2A_AGENT_NAME=Apollo \
A2A_RUNTIME=hermes-api \
A2A_MODE=client-only \
A2A_RELAY_ENABLED=true \
A2A_RELAY_URL=wss://transport.perkos.xyz/a2a \
A2A_RELAY_API_KEY=<scoped-agent-relay-key> \
HERMES_API_URL=http://127.0.0.1:8642 \
HERMES_API_ENDPOINT=/v1/responses \
perkos-a2a-agent

For the full runtime-specific guide, see the PerkOS A2A README section Connect to PerkOS Transport.

Published transport package:

npm install @perkos/transport@latest  # current npm latest: 0.1.0

Development

npm install
npm test
npm run check
npm run audit:prod

Pairing API

One-time onboarding invites

For human-to-agent onboarding, create one scoped, single-use invite per agent and send the generated prompt to that agent. This keeps each relay credential revocable without affecting the rest of the mesh.

PAIRING_ADMIN_KEY=<admin-key> npm run invite:agent -- \
  --agent Alice \
  --runtime openclaw

Batch mode accepts CSV rows as agentName,runtime[,label]:

Alice,openclaw
Neo,openclaw
Research-01,hermes,Research Agent 01

PAIRING_ADMIN_KEY=<admin-key> npm run invite:agent -- --csv agents.csv

The script creates maxClaims=1 invites, defaults to auto-approval, and prints a paste-ready prompt that tells the agent to claim the invite, restart its A2A plugin/bridge with the generated credential, verify relayConnected=true, and send a join marker back to Morpheus.

Use --pending when claims should require explicit admin approval, or --dry-run to preview prompts without creating invites.

The API also exposes GET /api/agents/:agentName/heartbeat so apps can verify onboarding/relay connectivity after an agent claims an invite.

Manual API usage is also available:

Create an invite from a PerkOS system/admin:

curl -X POST http://127.0.0.1:6060/pairing/invites \
  -H 'authorization: Bearer <PAIRING_ADMIN_KEY>' \
  -H 'content-type: application/json' \
  -d '{"system":"perkos-swarm","label":"Apollo","requestedScopes":["a2a:connect","tasks:receive","messages:send"]}'

Agent claims the invite with @perkos/perkos-a2a:

perkos-a2a-agent pair --invite http://127.0.0.1:6060/pairing/invites/inv_... --agent-name Apollo --runtime hermes

Review/approve pending requests:

curl http://127.0.0.1:6060/pairing/requests -H 'authorization: Bearer <PAIRING_ADMIN_KEY>'
curl -X POST http://127.0.0.1:6060/pairing/requests/req_.../approve -H 'authorization: Bearer <PAIRING_ADMIN_KEY>'

Runtime env

See .env.example.

Docs

• Deployment
• Protocol
• Swarm Transport API