Networks
Private networks - group-level connectivity without bilateral trust.
On this page
Overview
Networks are the group-level access control primitive in Pilot Protocol. Where bilateral trust requires every pair of agents to independently negotiate a handshake, a network grants connectivity to all members at once.
Add 10 agents to the same network and they can all discover and connect to each other immediately - no handshake ceremony, no approval queues, no N² trust pairs. The network boundary is the trust boundary.
Networks are managed through the pilotctl network commands - create networks, add agents, monitor status, and control membership from the CLI. Private Network is in early access; the team onboards deployments directly.
Networks vs. bilateral trust
Pilot Protocol has two distinct access control models. They serve different purposes and can be used together.
| Bilateral trust | Network membership | |
|---|---|---|
| Scope | One-to-one | Group-wide |
| Setup | Handshake + approve per pair | Add to network once, connect to all members |
| Scaling | O(n²) handshakes for n agents (e.g. 10 agents = 45 pairs) | O(n) adds for n agents |
| Discovery | Must know address or hostname | Enumerate via pilotctl network members |
| Revocation | Per-peer (untrust) | Remove from network; all access revoked at once |
| Use case | Cross-org collaboration, unknown peers | Teams, fleets, same-org agents |
| Persistence | Stored locally on each node | Stored in registry, survives any node restart |
Bilateral trust is designed for relationships between agents that don’t share an organizational boundary - two companies collaborating, an agent reaching out to an unknown peer, or any scenario where explicit mutual consent matters.
Networks are designed for agents that should be able to talk to each other by default - a fleet of workers, a team’s agents, a research cluster. Membership in the same network implies the authorization to communicate.
What network membership grants
When two agents share a network, they get a specific set of permissions that would otherwise require bilateral trust:
| Permission | Without network | With shared network |
|---|---|---|
| Discover addresses | Private agents are invisible | Can resolve any member’s endpoint |
| Open connections | Connection attempts silently dropped | Connections accepted immediately |
| Send datagrams | Silently dropped | Delivered |
| List members | Cannot enumerate the network | Full member list via pilotctl network members |
| Handshake auto-approval | Requires manual approve or mutual request | Network membership serves as a trust signal |
What networks do NOT grant
- No traffic inspection - encryption is end-to-end between agents. The network grants connectivity, not visibility.
- No 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.
Enterprise networks
Enterprise networks add a full suite of production controls on top of standard network membership. Enable enterprise at creation time with pilotctl network create --name prod --enterprise.
- RBAC - three-tier roles (owner, admin, member) with a permissions matrix. Promote, demote, kick, and transfer ownership.
- Invites - consent-based invite flow with 30-day TTL and inbox cap.
- Identity & SSO - OIDC, SAML, Entra ID, LDAP, and webhook identity providers with built-in JWT validation.
- Directory sync - push AD/Entra ID/LDAP entries to auto-provision members and roles.
- Policies - membership caps, port whitelists, and network descriptions with merge-on-update semantics.
- Audit & compliance - structured audit events, SIEM export (Splunk HEC, CEF, JSON), webhooks with DLQ.
- Blueprints - declarative JSON provisioning: one document, one command, full network setup.
See the Enterprise documentation for the full guide, or the CLI reference for enterprise commands.
The design principle
Standard network permissions are intentionally simple: you are either a member or you are not. Inside the boundary, communication is unrestricted. Outside, private agents are invisible. Enterprise networks add roles and port policies for organizations that need finer-grained control.
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. The backbone provides:
- 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. Being on the backbone means you exist in the address space, not that anyone can connect to you. Private agents on the backbone are invisible to everyone except their trusted peers and network co-members.
Join rules
When you create a network with pilotctl network create, you choose a join rule that controls how new members are added:
| Rule | Who can join | Use case |
|---|---|---|
| Open | Any node can join without approval | Public communities, open collaboration spaces |
| Invite only | Only when an owner or admin invites them | High-security environments where membership is tightly controlled |
| Token-gated | Anyone with the shared secret token | Teams that can distribute a token out-of-band (Slack, email, config file) |
The join rule is set at network creation and enforced by the registry. For token-gated networks, share the token out-of-band and agents self-join:
pilotctl network join 1 --token my-secretNetwork lifecycle
Create a network
pilotctl network create --name research-lab --join-rule token --token my-secretThe --join-rule is one of open, invite, or token. Use --enterprise to enable RBAC, policies, audit, and blueprints. See Plans for tier details.
Add agents
Admins add agents by identifier:
| Format | Example | Where to find it |
|---|---|---|
| Node ID | 1001 | pilotctl info output |
| Pilot address | 1:0001.0000.03E9 | Daemon startup output |
| Hostname | my-agent | Set at daemon start with --hostname |
pilotctl network invite 1 --node 1001Once added, the agent can immediately communicate with all other network members.
Monitor agents
List live members with pilotctl network members <network_id> - shows Pilot address, node ID, hostname, real endpoint, and online status for every agent in the network.
Remove agents
pilotctl network kick 1 --node 1001Access is revoked immediately - the agent can no longer resolve, connect to, or be discovered by other network members (unless they also share bilateral trust).
Delete a network
Owners can delete a network with pilotctl network delete <network_id>. All member associations are removed. Agents retain their backbone registration and bilateral trust relationships, but lose all network-granted permissions.
How it works under the hood
Network membership is checked automatically at three points in the protocol. You don’t need to configure any of this - it happens transparently when agents communicate.
1. Address resolution
When agent A looks up agent B’s endpoint, the registry checks: is B public? If not, does A share a network with B, or do they have mutual trust? If neither, the lookup is denied with no information leaked.
2. Connection acceptance
When a connection request arrives at a private agent, the daemon checks the source against its trust list and shared network membership. If neither applies, the request is silently dropped - no response, no indication the target exists.
3. Datagram delivery
Datagrams 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 boundary
The network security model is deliberately simple: membership equals access. Standard networks have no traffic inspection - list the members with pilotctl network members, and you know exactly who can communicate with whom. Enterprise networks layer on RBAC (owner/admin/member roles) and port-level policies for finer-grained control.
Silent rejection
When a non-member tries to connect to a private network agent, nothing happens. No error, no response, no indication the target exists. This prevents scanning and enumeration.
Backbone isolation
Backbone (network 0) membership does not grant any communication rights. Private agents on the backbone are invisible to everyone outside their trust and network boundaries.
Immediate revocation
Running pilotctl network kick revokes the agent’s access immediately. The next connection attempt will be silently dropped. There is no cache or propagation delay - the registry is the single source of truth.
No transitive trust
Network membership is not transitive. If A and B share network 1, and B and C share network 2, A cannot reach C through B unless A and C also share a network or have bilateral trust. Each network is an independent trust domain.
Enterprise port policies
Enterprise networks support port-level policies that restrict which ports members can access. Use pilotctl network policy <network_id> --set allowed_ports=80,443,1001 to limit accessible ports within a network. See Network Policies for details on membership caps, port whitelists, and merge-on-update semantics.