Networks

Private networks — group-level connectivity without bilateral trust.

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.

All network management happens through the Pilot Console — a web dashboard where you create networks, add agents, monitor status, and control membership from a browser.

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	O(n) adds for n agents
Discovery	Must know address or hostname	See all members in the console
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 visible in the console
Handshake auto-approval	Requires manual approve or mutual request	Network membership serves as a trust signal

What networks do NOT grant

• No per-port restrictions — members can reach all ports on other members. Port-level policies are a future roadmap item.
• No roles — all members have equal network access. Membership management happens in the console, not within the network.
• 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.

The design principle

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. This replaces complex ACLs with a single, auditable membership list.

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 in the console, you choose a join rule that controls how new members are added:

Rule	Who can join	Use case
Invite only	Only when you add them through the console	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, the console displays the join token and a ready-to-paste CLI command that agents can use to self-join:

pilotctl join-network 1 --token my-secret

Network lifecycle

Create a network

In the console, click Create Network and fill in:

1. Name — lowercase alphanumeric with hyphens (e.g., research-lab, prod-fleet)
2. Join rule — invite only or token-gated

Your first network is free (up to 5 agents). Additional networks or larger teams require a Pro plan.

Add agents

On the network detail page, click Add node. The form accepts three identifier formats:

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

Type any of these into the input field and click Add. The console resolves the identifier automatically. Once added, the agent appears in the Active Nodes table and can immediately communicate with all other network members.

Monitor agents

The Active Nodes table on the network detail page shows each agent’s live status: online/offline indicator, Pilot address, node ID, hostname, real endpoint, and capability flags. You can see at a glance which agents are connected and reachable.

Remove agents

Click Remove next to any agent in the Active Nodes table. 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).

Delete a network

Click Delete on the network detail page (requires confirmation). 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. There are no roles, no per-port policies, and no traffic inspection within a network. This makes the model easy to reason about and audit — look at the member list in the console, and you know exactly who can communicate with whom.

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

Click Remove in the console and the agent’s access is revoked 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.

Future: tag-based policies

The roadmap includes tag-based access policies that add port-level control within networks: “agents tagged frontend can reach agents tagged api on ports 80 and 443.” See the enterprise roadmap for details.