Network Policies

Early access. Enterprise policy controls are available in assisted deployments and may evolve during rollout.

Network policies allow owners and administrators to enforce constraints on enterprise networks. These policies control the number of agents that can join, which ports are accessible, and the metadata 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 to be changed are sent, and unmentioned fields keep their current values. This allows for partial updates.

MaxMembers

This policy caps the total number of agents that can be members of the network at any given time. The owner is included in this count.

A join attempt on a network at capacity is rejected with a “membership limit reached” error.
An invite acceptance on a network at capacity is rejected. The invite remains pending.
A value of 0 means there is no limit, which is the default.
Reducing the cap below the current member count is rejected. Members must be removed before the cap can be lowered.

pilotctl network policy <network_id> --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 dropped.

An empty list is the default and allows all ports.
A non-empty list restricts access to only the listed ports.
A maximum of 100 ports can be specified per policy.

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

To reset the port whitelist and allow all ports, set an empty list 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 a connection.

Description

A free-text metadata field for the network, used for human-readable context.

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.

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

Policy fields are at the top level of the message. The `pilotctl network policy` command builds this message. Only include 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.

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

Every policy change emits a `network.policy_changed` audit event. It records the network ID, old and new `max_members` values, and the old and new `allowed_ports` counts. Description changes are not recorded.

Programmable (expr) policies

An enterprise network can have a programmable expression policy, which is a versioned document of rules using the `expr-lang` language. The policy runner evaluates these rules on membership events. This is managed with its own RPCs, separate from the static policy record.

The protocol command to set an expr policy is `set_expr_policy`. It requires an owner or admin role, or an admin token. The `expr_policy` field is required and must declare `"version": 1` and at least one rule. An empty string or `"null"` clears the policy.

{
  "type": "set_expr_policy",
  "network_id": 1,
  "expr_policy": {
    "version": 1,
    "rules": [ /* ... */ ]
  },
  "admin_token": "your-admin-token"
}

The reply is `{"type": "set_expr_policy_ok", "network_id": 1}`. Setting or clearing an expr policy emits a `network.expr_policy_set` or `network.expr_policy_cleared` audit event.

The protocol command to get an expr policy is `get_expr_policy`. It returns `{"type": "get_expr_policy_ok", "network_id": N, "expr_policy": {...}}`. The `expr_policy` field is omitted if the network has no programmable policy.

The Go SDK registry client exposes `SetExprPolicy` and `GetExprPolicy` functions. Blueprints can provision the same document via the `expr_policy` field.

Member tags

Member tags are admin-assigned labels for a specific node within a network. They are distinct from a node's capability tags. Programmable policies use these tags for matching.

The protocol command to set member tags is `set_member_tags`. It requires an admin token and takes `network_id`, `target_node_id`, and a `tags` array. The array has a maximum of 10 tags, which must be lowercase alphanumeric with hyphens. An empty array clears the tags.

{
  "type": "set_member_tags",
  "network_id": 1,
  "target_node_id": 42,
  "tags": ["gpu", "us-east"],
  "admin_token": "your-admin-token"
}

The command returns `{"type": "set_member_tags_ok", ...}` and emits a `member_tags.changed` audit event.

The protocol command to get member tags is `get_member_tags`. It takes a `network_id` and a `target_node_id`. If `target_node_id` is 0, it returns tags for every member.

The Go SDK exposes `MemberTagsGet` and `MemberTagsSet` functions for these operations.

Persistence

Policies are stored in the network record in the registry and persist across restarts via the atomic JSON snapshot system.

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