Networks are a group-level access control primitive in Pilot Protocol. They grant connectivity to all members at once, removing the need for individual handshakes between every pair of agents.
Overview
Networks grant connectivity to all members of a group simultaneously. Adding agents to the same network lets them discover and connect without creating bilateral trust for every pair. Membership is a group-level network grant; enterprise port policy and application authorization can further narrow access.
Any node can list, join, leave and inspect networks with the pilotctl network commands. Creating a network needs the registry admin token. On the public backbone run by Vulture Labs only the operators hold that token, so you can join networks there only when the operators created one and gave you its token or an invite. To create and run your own networks, run your own registry: see Self-hosting the registry.
Networks vs. bilateral trust
Pilot Protocol has two access control models: bilateral trust and network membership. They serve different purposes and can be used together.
Bilateral trust:
Scope: One peer pair
Setup: Each side approves a handshake
Scaling: O(n squared) relationships for a fully connected fleet
Discovery: Reachable endpoint withheld until trust; some directory metadata may remain visible
Revocation: Either peer can revoke the relationship
Use case: Cross-organization or individually approved peers
Persistence: Stored by each daemon and survives restarts
What network membership grants
When two agents share a network, they gain a specific set of permissions:
Resolve endpoints: Members can resolve one another. Without trust or a shared network, the reachable endpoint is withheld while some directory metadata may remain visible.
Open connections: Connection attempts from members are accepted. Otherwise, they are silently dropped.
Send datagrams: Datagrams from members are delivered. Otherwise, they are silently dropped.
List members: A full member list is available via `pilotctl network members`.
Handshake auto-approval: Network membership serves as a trust signal.
Network membership does not grant:
Traffic inspection: Encryption is end-to-end between agents. The network grants connectivity, not visibility.
Transitive access: If A and B share network 1, and B and C share network 2, A cannot reach C. Each network is an independent trust domain.
Business authority: Membership does not independently authorize a task, tool call, protected-data disclosure, payment, or other consequential action.
Enterprise mode adds production controls. It is enabled at creation with `pilotctl network create --name prod --enterprise` on a registry where you hold the admin token. Features include:
RBAC: Three-tier roles (owner, admin, member).
Invites: A consent-based invite flow.
Identity & SSO: OIDC/JWT validation plus external identity mapping and webhook-based bridges.
Directory sync: Map external directory entries and roles to existing agents; sync does not create agents or add members.
Policies: Membership caps, port whitelists, and network descriptions.
Audit log & export: Structured audit events and SIEM export.
Blueprints: Declarative JSON provisioning.
The backbone (network 0)
Every registered agent belongs to network 0, the backbone. This is the global address space where node IDs are allocated and endpoints are registered.
Address allocation: 32-bit node IDs assigned at registration.
Endpoint resolution: Public IP:port discovery via STUN.
NAT traversal: Hole-punching and relay coordination.
Handshake relay: Trust negotiation via the registry.
The backbone does not grant communication rights. A private agent's endpoint is withheld from everyone except its trusted peers and network co-members.
Join rules
Whoever creates a network with `pilotctl network create` chooses a join rule that controls how new members are added.
Open: Any node can join without approval. Used for internal fleets.
Invite only: Only nodes an owner or admin invites, once they accept. Needs enterprise mode. Used for high-security environments.
Token-gated: Anyone with a shared secret token can join. Used for teams that can distribute a token out-of-band.
For token-gated networks, agents can self-join with the token:
This needs the registry admin token (PILOT_ADMIN_TOKEN or admin_token in ~/.pilot/config.json). The `--join-rule` is one of `open` (the default), `invite`, or `token`; `invite` requires `--enterprise`, which enables roles, invites, directory sync and port policies. `--node-id` sets the creating node, which becomes the owner.
How a node gets in depends on the join rule. On open and token networks, agents join themselves:
On invite-only networks, an owner or admin invites the agent from their own node (by node ID, Pilot address or hostname), and the invited agent accepts. Invites expire after 30 days.
# On an owner or admin node
pilotctl network invite 1 1001
pilotctl network invite 1 my-agent
# On the invited node
pilotctl network invites
pilotctl network accept 1 # or: pilotctl network reject 1
With the registry admin token you can also join another node to an open or token network: `pilotctl network join 1 --node-id 1001` (add `--token` for a token network). Invite-only networks always go through the invite. Once a node is a member, it can communicate with all other network members.
To monitor agents, list live members with `pilotctl network members <network_id>`. This shows node ID, hostname, version, and public status. JSON mode includes additional fields.
To remove agents:
pilotctl extras network kick 1 1001
# or by hostname / pilot address
pilotctl extras network kick 1 my-agent
Kicking needs the registry admin token or the network’s own admin token. A member can also leave on its own with `pilotctl network leave 1`. Access is revoked immediately. With the admin token, `pilotctl extras network delete <network_id>` deletes a network and removes all member associations.
How it works under the hood
Network membership is checked automatically at three points in the protocol.
Address resolution: When agent A looks up agent B’s endpoint, the registry checks if B is public. If not, it checks if A and B share a network or have mutual trust. If neither is true, the endpoint lookup is denied, though other directory metadata may be returned.
Connection acceptance: When a connection request arrives at a private agent, the daemon checks if the source is on its trust list or is a member of a shared network. If not, the request is silently dropped.
Datagram delivery: Datagrams sent to private agents use the same check. If the sender is not trusted and not in a shared network, the datagram is silently dropped.
Security model
Membership is the connectivity boundary: Standard membership grants network connectivity. Enterprise networks add RBAC and port-level policies; application authorization remains separate.
Silent rejection: A non-member connection request is dropped without an endpoint-level response. Directory metadata may still be enumerable under some registry configurations.
Backbone isolation: Backbone (network 0) membership does not grant any communication rights. A private agent's endpoint is hidden.
Immediate revocation: `pilotctl extras network kick` revokes an agent’s access at the connection gate immediately; a kicked peer's next connection attempt re-checks the registry and is silently dropped. Membership metadata is not instant everywhere: daemons reconcile network membership on a periodic sync loop (every 5 minutes) and resolve/policy results are cached, so listings and cached lookups can briefly lag the registry, which remains the single source of truth.
No transitive trust: Network membership is not transitive. Each network is an independent trust domain.
Enterprise port policies: Enterprise networks support port-level policies to restrict which ports members can access. With the admin token, use `pilotctl extras network policy <network_id> --allowed-ports 80,443,1001` to set them.