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.
Networks are managed through the pilotctl network commands. Private Network is in early access.
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 networks add production controls. They are enabled at creation with `pilotctl network create --name prod --enterprise`. 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 & compliance: 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
When creating a network with `pilotctl network create`, a join rule must be chosen to control how new members are added.
Open: Any node can join without approval. Used for internal fleets.
Invite only: Only an owner or admin can invite new members. 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:
The `--join-rule` is one of `open`, `invite`, or `token`. Use `--enterprise` to enable enterprise features.
Admins add agents by Node ID, Pilot address, or hostname.
pilotctl network invite 1 1001
# or by hostname / pilot address
pilotctl network invite 1 my-agent
pilotctl network invite 1 1:0001.0000.03E9
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 network kick 1 1001
# or by hostname / pilot address
pilotctl network kick 1 my-agent
Access is revoked immediately. Owners can delete a network with `pilotctl network delete <network_id>`, which 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 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. Use `pilotctl network policy <network_id> --allowed-ports 80,443,1001` to set them.