[ Switch to styled version → ]
Networks are a group-level access control primitive in Pilot Protocol. A network grants connectivity to all its members at once, an alternative to establishing trust between every pair of agents.
Networks grant connectivity to all members at once. Adding multiple agents to the same network allows them to discover and connect to each other without individual handshake ceremonies. The network boundary is the trust boundary.
Networks are managed through the `pilotctl network` commands. Private Network is in early access.
Pilot Protocol has two access control models that can be used together.
Bilateral trust is for relationships between agents that do not share an organizational boundary. Networks are for agents that should be able to communicate by default.
When two agents share a network, they gain a specific set of permissions.
Network membership does not grant traffic inspection or transitive access.
Enterprise networks add production controls. Enable at creation with `pilotctl network create --name prod --enterprise`.
Standard network permissions are simple: a member can communicate inside the boundary, and is invisible outside. Enterprise networks add roles and port policies for finer-grained control.
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 does not grant communication rights. Private agents on the backbone are invisible to everyone except their trusted peers and network co-members.
A join rule, set with `pilotctl network create`, controls how new members are added.
For token-gated networks, agents self-join with the token:
pilotctl network join 1 --token my-secretTo 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 enterprise features.
Admins add agents by identifier:
pilotctl network invite 1 1001
# or by hostname / pilot address
pilotctl network invite 1 my-agent
pilotctl network invite 1 1:0001.0000.03E9Once added, the agent can communicate with all other network members. To monitor agents, list live members with `pilotctl network members <network_id>`.
To remove agents:
pilotctl network kick 1 1001
# or by hostname / pilot address
pilotctl network kick 1 my-agentAccess is revoked immediately. To delete a network, owners can use `pilotctl network delete <network_id>`. All member associations are removed.
Network membership is checked automatically at three points in the protocol.
1. Address resolution: When agent A looks up agent B, the registry checks if B is public. If not, it checks if A and B share a network or have mutual trust. Otherwise, the lookup is denied.
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.
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 dropped.
The network security model is that membership equals access. Standard networks have no traffic inspection. Enterprise networks add RBAC and port-level policies.
When a non-member tries to connect to a private network agent, the request is silently rejected to prevent scanning.
Backbone (network 0) membership does not grant any communication rights.
Running `pilotctl network kick` revokes access immediately, with no propagation delay.
Network membership is not transitive. Each network is an independent trust domain.
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 a policy. Other flags include `--max-members <n>` and `--description <text>`. Without any `--<flag>` argument, `pilotctl network policy <network_id>` shows the current policy.