Network Policies

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.

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 allows for partial updates; for example, setting max_members does not reset allowed_ports.

MaxMembers

This policy 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

# Set a membership cap of 50 agents
pilotctl network policy <network_id> --set max_members=50

AllowedPorts

This policy 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

# 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. 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> --set description="Production fleet - US East region"

Setting policies

To set a policy:

pilotctl network policy <network_id> --set max_members=50 --set 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 semantics apply: only include the fields to be changed. 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.

# Example response
{
  "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 have the same policies as the primary.