Agent Control Protocol

Status: Current

Last reviewed: 2026-05-10

The agent control protocol is defined in common/proto/agent.proto in both nexus-backend and nexus-agent.

Service

service AgentService {
  rpc Register(RegisterRequest) returns (RegisterResponse);
  rpc Heartbeat(stream HeartbeatRequest) returns (stream HeartbeatResponse);
  rpc StreamConfig(ConfigRequest) returns (stream ConfigUpdate);
  rpc ReportMetrics(MetricsReport) returns (MetricsAck);
}

Registration

RegisterRequest carries:

• node_id
• hostname
• public_ip
• agent_version
• node_secret
• connect_address
• multiplex
• multiplex_port

RegisterResponse returns:

• accepted
• assigned_id
• message
• initial_config

Heartbeat

Heartbeat is a bidirectional stream.

Agent sends:

• node_id
• sequence
• timestamp
• CPU and memory usage.
• uptime.
• repeated peer link metrics.

Backend responds with:

• ok
• ack_sequence
• optional commands.

Current command enum includes:

• RELOAD_CONFIG
• RESTART_PINGORA
• RUN_DIAGNOSTICS

Config Streaming

StreamConfig is server-streaming.

ConfigUpdate can carry:

• PingoraConfig
• NodeConfig

NodeConfig carries connectivity settings:

• connect_address
• multiplex
• multiplex_port

PingoraConfig carries:

• upstream clusters.
• TCP proxy rules.
• HTTP proxy rules.
• TLS config.
• QUIC rules.
• UDP rules.

Transport Profiles

Transport profiles separate payload protocol, outer transport, and security layer.

Current protobuf enums:

PayloadProtocol:
  TCP
  UDP

OuterTransport:
  TCP
  UDP
  QUIC

SecurityLayer:
  RAW
  TLS
  REALITY
  NOISE

Roadmap note: L3PTP will add payload=ip conceptually. The protobuf enum has not been extended yet. See Transport Composition.

Rule Types

TcpProxyRule

Supports:

• RAW/TLS/REALITY mode.
• inbound REALITY private key and metadata.
• outbound/upstream REALITY.
• outbound/upstream QUIC REALITY.
• transport profile.

UdpRule

Supports:

• RAW/ENC mode.
• UDP Noise key material.
• outbound/upstream QUIC REALITY DATAGRAM.
• transport profile.

QuicRule

Supports:

• QUIC REALITY listener.
• REALITY server names, short IDs, target host, and target port.
• max streams per connection.
• transport profile.

Metrics

MetricsReport contains:

• connection metrics.
• bandwidth metrics.
• Pingora metrics.

DATAGRAM-specific performance counters currently live in the agent implementation and test logs; formal control-plane reporting for those counters is still a roadmap item.