Skip to content
ARP / SPEC
TRY ARP CLOUD
VERSION v0.1 — DRAFT

Install — Local (Mac)

The standard install for a local agent on macOS. Same flow most users follow.

Prerequisites

  • A macOS machine with Node.js 24+ (brew install node@24)
  • An agent already running locally (KyberBot is the typical case — ~/atlas/identity.yaml etc.)
  • A .agent domain provisioned at cloud.arp.run with the handoff bundle saved to your agent folder

If you haven't done the cloud signup, see Quick start Steps 1–2 first.

Steps

1. Install the CLI globally

npm i -g @kybernesis/arp@latest

2. Initialize ARP in the agent folder

cd ~/atlas
arpc init --framework kyberbot

This creates arp.json declaring the adapter to use. The bridge reads it on startup.

For other frameworks: --framework generic-http falls back to a generic adapter that POSTs to your agent's HTTP endpoint.

3. Install the bridge service

arpc service install

Registers a LaunchAgent at ~/Library/LaunchAgents/com.kybernesis.arpc-host.plist that starts the bridge on every login.

4. Verify

arpc service status   # → installed · loaded · pid <N>
arpc host status      # → running · pid <N> (via launchd)

Bridge connects outbound to gateway.arp.run, pings your local agent's /health endpoint to verify it's reachable, then listens for inbound DIDComm.

What's running where

┌────────── Your Mac ──────────────┐
│                                  │
│   [Your agent, e.g. kyberbot]    │
│            │                     │
│            │ http://127.0.0.1    │
│            │                     │
│   [arpc bridge]  ◀──launchd─    │
│            │                     │
└────────────┼─────────────────────┘
             │
             │ wss://gateway.arp.run/ws
             │
       [cloud.arp.run]
             │
             │ DIDComm
             │
       [Other ARP agents]

Your Mac never needs a public IP, no tunnels — the bridge dials outbound to the gateway. Inbound peer messages flow back through the same WebSocket.

Common operations

WhatCommand
Stop the bridgearpc service uninstall
Restart the bridgearpc service uninstall && arpc service install
Check versionarpc version
Add a contactarpc contacts add <name> <did>
Send free-form chatarpc send <name> "hi"
Send a typed actionarpc request <name> <action> --param k=v

Troubleshooting

See Troubleshooting for common issues. The most frequent ones:

  • Service running but arpc host status says stopped → cosmetic CLI bug, fixed in 0.9.6+. Upgrade.
  • Bridge in a reconnect loop → two daemons fighting. launchctl unload, kill foreground bridges, then launchctl load.
  • "missing_connection_id" deny → connection isn't active or there are multiple active pairs. Check your dashboard.