Flow

Network Policies

Membership caps, port whitelists, and network metadata for enterprise networks.

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: you only send the fields you want to change, and unmentioned fields keep their current values. This makes partial updates safe — setting max_members does not reset allowed_ports.

MaxMembers

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

Behavior	What happens
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

# Set a membership cap of 50 agents
pilotctl network policy <network_id> --set 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.

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

# Allow only HTTP, HTTPS, and data exchange ports
pilotctl network policy <network_id> --set allowed_ports=80,443,1001

# Reset to allow all ports
pilotctl network policy <network_id> --set 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. Use it for human-readable context: purpose, team name, environment, or compliance notes.

Constraint	Value
Maximum length	256 characters
Default	Empty string

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

Setting policies

Set a policy

pilotctl network policy <network_id> --set max_members=50 --set allowed_ports=80,443

Protocol command: set_network_policy. Requires owner or admin role (or 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 you want to change. Omitted fields are preserved.

Get a policy

pilotctl network policy <network_id>

Protocol command: get_network_policy. Returns the current policy for the network.

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

Audit trail

Every policy change emits a network.policy_changed audit event with the network ID and the updated policy fields (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 exactly as they were.

Policy state is also included in HA replication snapshots, so standby registries have the same policies as the primary.