Networks

Networks are the group-level access control primitive in Pilot Protocol. A network grants connectivity to all its members at once, without requiring individual handshakes between every pair of agents.

Overview

Networks are a group-level access control primitive. Where bilateral trust requires every pair of agents to negotiate a handshake, a network grants connectivity to all members at once.

Adding agents to the same network allows them to discover and connect to each other. The network boundary is the trust boundary.

Networks are managed through `pilotctl network` commands. Private Network is in early access.

Networks vs. bilateral trust

Pilot Protocol has two access control models that can be used together.

Scope: Bilateral trust is one-to-one. Network membership is group-wide.
Setup: Bilateral trust requires a handshake and approval per pair. Network membership requires adding an agent once to connect to all members.
Scaling: Bilateral trust requires O(n²) handshakes for n agents. Network membership requires O(n) additions.
Discovery: With bilateral trust, an agent's address or hostname must be known. Network members can be enumerated via `pilotctl network members`.
Revocation: Bilateral trust is revoked per-peer. Removing an agent from a network revokes all its network access at once.
Use case: Bilateral trust is for cross-organization collaboration or unknown peers. Networks are for teams, fleets, or same-organization agents.
Persistence: Bilateral trust is stored locally on each node. Network membership is stored in the registry and survives node restarts.

Bilateral trust is for relationships between agents that do not share an organizational boundary, or any scenario where explicit mutual consent is required.

Networks are for agents that should be able to communicate by default, such as a fleet of workers or a research cluster. Membership implies 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.

Discover addresses: Members can resolve any other member's endpoint. Without a shared network, private agents are invisible.
Open connections: Connection attempts from network members are accepted. Attempts from non-members are silently dropped.
Send datagrams: Datagrams from network members are delivered. Datagrams from non-members 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.

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 add 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.
Invites: A consent-based invite flow.
Identity & SSO: OIDC, SAML, Entra ID, LDAP, and webhook identity providers.
Directory sync: Push AD/Entra ID/LDAP entries to auto-provision members and roles.
Policies: Membership caps, port whitelists, and network descriptions.
Audit & compliance: Structured audit events and SIEM export.
Blueprints: Declarative JSON provisioning for network setup.

Standard network permissions are simple: a user is either a member or not. Inside the boundary, communication is unrestricted. Enterprise networks add roles and port policies for 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. Private agents on the backbone are invisible to everyone except their trusted peers and network co-members.

Join rules

When creating a network with `pilotctl network create`, a join rule controls how new members are added.

Open: Any node can join without approval. For public communities or open collaboration spaces.
Invite only: Members can join only when an owner or admin invites them. For high-security environments.
Token-gated: Anyone with the shared secret token can join. For teams that can distribute a token out-of-band.

The join rule is set at network creation. For token-gated networks, agents self-join with the token:

pilotctl network join 1 --token my-secret

Network lifecycle

To create a network:

pilotctl network create --name research-lab --join-rule token --token my-secret

The `--join-rule` is one of `open`, `invite`, or `token`. Use `--enterprise` to enable RBAC, policies, audit, and blueprints.

Admins add agents by identifier, which can be a Node ID, Pilot address, or hostname.

pilotctl network invite 1 --node 1001

Once added, the agent can communicate with all other network members.

List live members with `pilotctl network members <network_id>`. This shows Pilot address, node ID, hostname, real endpoint, and online status for every agent in the network.

To remove an agent:

pilotctl network kick 1 --node 1001

Access is revoked immediately. The agent can no longer resolve, connect to, or be discovered by other network members, unless they also share bilateral trust.

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.

How it works under the hood

Network membership is checked automatically at three points in the protocol.

1. Address resolution

When agent A looks up agent B’s endpoint, the registry checks if B is public. If not, it checks if A shares a network with B or if they have mutual trust. If neither, 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 silently dropped.

Security model

The network security model is that membership equals access. Standard networks have no traffic inspection. Enterprise networks add RBAC roles and port-level policies for finer-grained control.

When a non-member tries to connect to a private network agent, the request is silently rejected with no response. This prevents scanning and enumeration.

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.

Running `pilotctl network kick` revokes an agent's access immediately. The registry is the single source of truth, so there is no cache or propagation delay.

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.

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.