Network Policies

Network policies allow owners and admins to enforce constraints on enterprise networks. These policies control membership caps, accessible ports, and network metadata.

Overview

Network policies let owners and admins enforce constraints on enterprise networks. Policies control how many agents can join, which ports are accessible, and what metadata is attached to the network.

Policies use merge-on-update semantics: only the fields sent are changed, and unmentioned fields keep their current values. This makes partial updates safe, as setting one field does not reset others.

MaxMembers

Caps the total number of agents that can be members of the network at any given time. The owner counts toward the cap.

Join attempt at capacity: Rejected with “membership limit reached”.
Invite accept at capacity: Rejected. The invite remains pending but the agent cannot join until a slot opens.
Value of 0: No limit (default).
Reducing below current count: Allowed. Existing members are not kicked, but no new members can join.

pilotctl network policy <network_id> --max-members 50

AllowedPorts

Restricts which Pilot ports are accessible within the network. When set, only connections to listed ports are permitted between network members. Connections to unlisted ports are silently dropped.

Empty list (default): All ports allowed.
Non-empty list: Only listed ports are accessible.
Maximum entries: 100 ports per policy.

pilotctl network policy <network_id> --allowed-ports 80,443,1001

To reset the port whitelist and allow all ports again, set an empty list directly via the registry RPC `set_network_policy` with `"allowed_ports": []`.

Port policies are enforced at the connection acceptance layer. The daemon checks the destination port against the network’s allowed ports list before accepting the connection.

Description

A free-text metadata field for the network. It can be used for human-readable context such as purpose, team name, environment, or compliance notes.

Maximum length: 256 characters.
Default: Empty string.

pilotctl network policy <network_id> --description "Production fleet - US East region"

Setting policies

To set a policy:

pilotctl network policy <network_id> --max-members 50 --allowed-ports 80,443

The protocol command is `set_network_policy`. It requires an owner or admin role, or an admin token.

{
  "command": "set_network_policy",
  "network_id": 1,
  "policy": {
    "max_members": 50,
    "allowed_ports": [80, 443],
    "description": "Production fleet"
  },
  "admin_token": "your-admin-token"
}

Merge-on-update: only include the fields to change. Omitted fields are preserved.

To get a policy:

pilotctl network policy <network_id>

The protocol command is `get_network_policy`. It returns the current policy for the network.

{
  "max_members": 50,
  "allowed_ports": [80, 443],
  "description": "Production fleet"
}

Every policy change emits a `network.policy_changed` audit event with the network ID and the updated policy fields, including old and new values.

Persistence

Policies are stored as part of the network record in the registry. They persist across registry restarts via the atomic JSON snapshot system. When the registry loads from a snapshot, all network policies are restored.

Policy state is also included in HA replication snapshots, so standby registries (started via rendezvous -standby <primary:port> -repl-token <token>) have the same policies as the primary.