Self-hosting the registry

Private networks, roles, identity, policies, audit export and blueprints in the open-source registry, for anyone who runs their own.

Who can use these features. Every operation in this section needs the registry admin token (some network operations also accept that network’s own admin token or an owner/admin role). On the public backbone run by Vulture Labs only the operators hold the admin token, so you can’t create or administer networks there. To use these features, run your own rendezvous and point your daemons at it.

Overview

The rendezvous server (github.com/pilot-protocol/rendezvous, AGPL-3.0) is the registry and beacon that daemons connect to. Besides addresses and trust, it can run networks with the controls a private deployment needs: role-based access control (RBAC), identity provider integration, membership policies, structured audit logging, and declarative provisioning through blueprints.

Plain networks treat membership as a binary boundary. Networks in enterprise mode add layers for access control (RBAC), identity and directory synchronization, traffic permissions (port policies), event logging (audit), and configuration (blueprints).

Run your own registry

One rendezvous process serves the registry (TCP) and the beacon (UDP). Set an admin token when you start it; with no token, network creation is disabled.

# Build and start the registry + beacon
git clone https://github.com/pilot-protocol/rendezvous
cd rendezvous && go build ./cmd/rendezvous
./rendezvous -registry-addr :9000 -beacon-addr :9001 \
  -store ./registry.json -admin-token "$PILOT_ADMIN_TOKEN"

# Point a daemon at it
pilotctl daemon start --registry registry.example.com:9000 --beacon registry.example.com:9001

# Admin commands read the registry address and token from the environment
export PILOT_REGISTRY=registry.example.com:9000
export PILOT_ADMIN_TOKEN=your-admin-token

pilotctl also reads the token from admin_token in ~/.pilot/config.json. The registry admin commands sit under `pilotctl extras`; run it with no arguments for the list. See Self-hosting for running the registry in production.

Enable enterprise mode

Enterprise mode is set per network. Enable it at creation time:

pilotctl network create --name prod-fleet --enterprise --join-rule invite

`network create` needs the registry admin token. `--join-rule` is `open` (the default), `token` (with `--token`), or `invite`, which requires `--enterprise`. The creator node (`--node-id`) becomes the network’s owner; enterprise mode is what makes the roles enforceable.

Feature summary

RBAC: Provides three-tier roles (owner, admin, member) with distinct permissions for promotion, demotion, kicking, and ownership transfer.
Invites: Invite agents to invite-only networks; the invited node accepts or rejects. Invites have a 30-day time-to-live (TTL) and an inbox cap of 100.
Identity & SSO: OIDC/JWT validation (RS256/HS256 against a JWKS) and a webhook for your own verification endpoint.
Directory sync: Maps external directory entries and roles to existing agents. It does not create agents or add network members.
Network policies: Enforces membership caps, port allowlists, and network descriptions.
Audit: Provides structured audit events in slog JSON format, stored in an in-memory ring buffer. Events can be exported to Splunk HEC, CEF/Syslog, or JSON endpoints.
Webhooks: Event-driven notifications with retry, a dead-letter queue, and Prometheus metrics.
Blueprints: Declarative JSON documents that provision an entire network, including its name, policies, identity provider, webhooks, audit export, and roles.
Key lifecycle: Manages agent key rotation, expiry dates, and blocks expired agents from heartbeating.

Enterprise gating

Some features require enterprise mode on the network, while others are available for all networks.

Features that require enterprise mode:

RBAC roles (promote, demote, kick)
Ownership transfer
Invite flow
Directory sync
Port policies

Features available to all networks:

Network create / join / leave / delete
Membership listing
Audit log query (global)
Key rotation
Hostname & visibility changes
Tags
Trust & handshakes
Per-network admin tokens
Blueprint provisioning

Attempting an enterprise operation on a non-enterprise network returns an error. The setting is toggled by the registry's `set_network_enterprise` RPC or the Go SDK's `client.Client.SetNetworkEnterprise`. Membership is preserved when toggling.

Network creation and deletion, per-network admin tokens and blueprint provisioning are gated by the admin token, not by enterprise mode. Blueprint provisioning only enables enterprise when the blueprint explicitly requests it.

What’s next

RBAC & Access Control: roles, permissions, invites, and the authorization chain.
Identity & SSO: validate OIDC/JWT credentials and connect other identity systems through a bridge you run.
Network Policies: membership caps, port allowlists, and metadata.
Audit Log & Export: structured logging, export to SIEMs, and webhooks.
Blueprints: provision entire networks from a single JSON document.