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

Install overview

Audience: developers + operators deploying an ARP runtime.

For end users, see Quick start — the practical install path that uses the managed cloud + local bridge CLI.

ARP is a protocol, not a single binary. There are several deployment modes; the right one depends on your agent's topology, your data sovereignty needs, and whether you want to run anything yourself.

The deployment modes

Mode A — Managed cloud (cloud.arp.run)

One-line: sign up at cloud.arp.run, install the arpc CLI on your agent's machine, run a tiny bridge process. We host the gateway, audit, and dashboard.

What we host:

  • The gateway runtime (DIDComm + WebSocket fanout)
  • Multi-tenant Postgres (Neon)
  • The owner dashboard at cloud.arp.run
  • Audit chain storage
  • Pairing UX
  • Cedar policy compilation (scope-catalog server)

What runs on your machine:

  • The arpc CLI + bridge service (one process, started by launchd / systemd)
  • A framework adapter (kyberbot, generic-http) that forwards ARP requests to your local agent

Pros: zero infra to operate. Works for any agent that has an HTTP-callable interface. Cons: the cloud sees connection metadata (who-talks-to-whom + decision/audit). Encrypted message bodies aren't visible to us, but the relationship graph is.

When to pick: consumer / SMB / single-developer use. The path most users will take.

Mode B — Self-hosted gateway

One-line: clone the monorepo, deploy apps/cloud-gateway to your own infra (Railway, Fly, your VPS), point bridges at it instead of gateway.arp.run.

The gateway is a stateless Node service that connects to a Postgres you also host. You run both.

Pros: full data sovereignty. You see the same audit chain we do, on your own database, hosted by you. Cons: you operate Postgres + the gateway. You handle TLS, scaling, backups, monitoring.

When to pick: privacy-strict orgs, regulated industries, anyone who wants the wire-level metadata to stay on their own infrastructure. See Cloud (self-host) for the deployment guide.

Mode C — Embedded library (@kybernesis/arp-sdk)

One-line: build ARP into your agent process directly. No separate bridge. The SDK is a Node library that exposes the same WebSocket + envelope-signing primitives the bridge uses.

Pros: lowest latency (in-process PDP eval). Tightest integration with your agent's lifecycle. Cons: Node-only at the moment (Python SDK in progress). Ties your agent's release cycle to ARP's; updates require a redeploy.

When to pick: custom agents you control end-to-end where the bridge subprocess feels like overhead. Most users should start with Mode A — switching to Mode C later is straightforward because the wire shape is identical.

What's actually shipping right now

ComponentStatusNotes
cloud.arp.run (managed gateway, dashboard)LivePublic
@kybernesis/arp (CLI / arpc)Publishednpm
@kybernesis/arp-cloud-bridgePublishedKyberBot, generic-http adapters bundled
@kybernesis/arp-cloud-clientPublishedWS client for bridge / SDK
@kybernesis/arp-pairing, -pdp, -scope-catalog, etc.PublishedBuilding blocks
apps/cloud-gateway (self-host gateway)Open source, deployableRailway / Fly templates pending
Mobile owner appPrivate repo, in progressiOS / Android via Expo

Frameworks with first-class adapters today:

  • KyberBot — native integration via @kybernesis/arp-cloud-bridge's kyberbot adapter, including typed /api/arp/* endpoints in KyberBot's server (data-layer policy enforcement)
  • Generic HTTP — any agent that exposes an HTTP endpoint can use the generic-http adapter as a fallback

Adapters for LangChain / LangGraph / CrewAI / Mastra / OpenClaw are roadmap items, not shipped. The protocol supports them; someone has to write the adapter package. See Framework adapters for the contract if you want to author one.

Picking a mode

Are you a typical user / single developer?
├─ Yes → Mode A (managed cloud)
└─ No
   │
   Is data sovereignty over connection metadata required (regulated, privacy-strict)?
   ├─ Yes → Mode B (self-hosted gateway)
   └─ No
      │
      Is your agent custom / greenfield / Node-based?
      ├─ Yes → Mode C (embedded library) — but Mode A still works
      └─ No → Mode A

90% of installs are Mode A. The CLI + cloud is the path we maintain best.

Operational minimums

Whatever mode you pick, the agent needs:

  • A way to make outbound HTTPS to your gateway (cloud.arp.run or your own)
  • A persistent local store for the bridge's auth state (~/.arp/host.yaml, the handoff bundle, plus per-connection rate-limit counters)
  • Clock sync (NTP) — token expirations and audit ordering depend on roughly accurate time
  • A running agent process the bridge can talk to over 127.0.0.1 (or wherever you point the adapter)

What it doesn't need:

  • A static public IP (bridges connect outbound to the gateway; no inbound port required)
  • A fixed hostname for the agent itself (the .agent domain points at our DID-doc hosting; the agent is reachable through the gateway)
  • Any specific OS — macOS + Linux are tested; Windows works with WSL

Switching modes later

The handoff bundle is portable. To switch:

  • Mode A → Mode B: change gateway_ws_url in arp.json to point at your gateway
  • Mode A → Mode C: keep the bundle, drop the bridge service, call the SDK from your agent code
  • Mode B → A: revert the gateway_ws_url

Existing connections persist across mode switches because they bind to the agent's DID, not the hosting.