Nodes

Status: Current

Last reviewed: 2026-05-13

Route: /nodes

Nodes represent NexusNet agents managed by the control plane.

Node Table

Column	Meaning
Status	Agent status. The current UI shows a status dot and tooltip/status text.
Name	Operator-facing node name.
ISO Code	Country code used for sorting and display context.
IPv4	Public IPv4 reported by or stored for the node.
IPv6	Public IPv6 reported by or stored for the node.
Last Heartbeat	Most recent agent heartbeat time, or Never.
Actions	View agent config, edit node, reset key, or delete node.

Create a Node

Required role: admin or operator

1. Open Nodes.
2. Click Add Node.
3. Optional: enter a custom control PSK. If omitted, the backend generates one.
4. Enter a node name, such as tokyo-edge-01.
5. Select an ISO 3166-1 alpha-2 country code.
6. Click Create.

The backend returns the control PSK once. Store it immediately or copy the agent environment block from the dialog.

Agent Environment

The generated environment block contains:

NEXUS_AGENT_ID=<node-id>
NEXUS_CONTROL_ENDPOINT=<display control endpoint from Settings>
NEXUS_CONTROL_PSK=<one-time control PSK>

The control endpoint comes from Settings > Connections. It is stored locally in the browser and only affects generated copy text.

Edit a Node

Required role: admin or operator

1. Click the edit action.
2. Change name or country code.
3. Save.

Current node edit UI exposes identity fields. Backend APIs also support connectivity fields used by agent config pushes.

Reset a Node Key

Required role: admin or operator

Use reset when a control PSK is lost or compromised.

1. Open the row action menu.
2. Click Reset key.
3. Confirm the warning.
4. Copy the new control PSK and update the agent environment.

Old agent processes using the previous PSK must be restarted or reconfigured.

Delete a Node

Required role: admin or operator

Deleting removes the node from the control plane. Check L3 tunnels and L4 chains first, because deployments that reference the node will no longer have a valid target.

Troubleshooting

Symptom	Check
Node stays offline	Confirm NEXUS_AGENT_ID, NEXUS_CONTROL_ENDPOINT, and NEXUS_CONTROL_PSK.
Generated config has blank control endpoint	Set Settings > Connections > Control endpoint.
Create fails with forbidden	Confirm your role is admin or operator, and registration secret is correct if configured.
Last heartbeat is Never	Agent has not authenticated and sent heartbeat yet.