User Guide

Status: Current

Last reviewed: 2026-05-15

This guide documents the current NexusNet console from a user and operator point of view. It follows the deployed frontend routes in nexus-frontend and the REST routes registered by nexus-backend.

Console Areas

Area	Route	Purpose
Login	/login	Sign in and start a JWT-backed console session.
Dashboard	/dashboard	View high-level node, route, upstream, health, and alert state.
Nodes	/nodes	Register, edit, reset, and inspect agent nodes.
L3 Tunnels	/gateway/l3-networks	Manage point-to-point IP tunnels over QUIC REALITY DATAGRAM.
L4 Chains	/gateway/l4-chains	Build deployable L4 forwarding pipelines.
Port Management	/nodes/ports	Inspect Nexus-owned listener ports, service lists, and agent runtime state.
L4 Upstreams	/gateway/l4-upstreams	Maintain reusable target endpoints and inbound SNI match names.
Security Credentials	/gateway/credentials	Manage X25519 keys, TLS certificates, and REALITY profiles.
Audit Log	/audit	Inspect configuration and system change history.
Users	/settings/users	Create users and review roles.
Settings	/settings	Update the current account, UI preferences, and local endpoint hints.
API-only features	REST API	Compatibility and admin features without first-class console pages.

Role Model

NexusNet has three roles:

Role	Typical access
admin	Full access, including user creation, TLS certificate writes, credential writes, and audit revert API access.
operator	Operational changes to nodes, L3 tunnels, L4 chains, upstreams, and deployments.
viewer	Read-only access to protected APIs and console pages.

Some buttons may still be visible to lower roles. The backend is authoritative: write requests that require a higher role return 403 Forbidden.

Common Workflows

Bring a Node Online

1. Sign in with an admin or operator account.
2. Open Settings > Connections and store the control endpoint used by agents.
3. If the backend has REGISTRATION_SECRET configured, store the registration secret in Settings > Connections.
4. Open Nodes and create a node.
5. Copy the one-time control PSK and generated agent environment block.
6. Start the agent with NEXUS_AGENT_ID, NEXUS_CONTROL_ENDPOINT, and NEXUS_CONTROL_PSK.
7. Return to Nodes and confirm the status dot becomes online after heartbeat.

Deploy an L4 Chain

1. Create any required targets in L4 Upstreams.
2. Create any required credentials in Security Credentials.
3. Open L4 Chains and build a chain with transit stages followed by one target stage.
4. Save the chain.
5. Click deploy. A success toast lists the nodes that received config.

Inspect L4 Listener Runtime State

1. Open Nodes > Port Management.
2. Select a node or keep All nodes.
3. Review the listeners derived from enabled L4 chains, L3 services, and any saved listener policies.
4. Open the service/order dialog to see each L4 or L3 service on that listener.
5. Open runtime preview to load the current agent-reported listener and route table from /api/nodes/ports/runtime.

Deploy an L3 Tunnel

1. Ensure two different nodes are registered and connected.
2. Create a REALITY profile in Security Credentials.
3. Open L3 Tunnels and create a point-to-point tunnel.
4. Select endpoint nodes, tunnel interface names, addressing, MTU, and allowed source CIDRs.
5. Save and deploy the tunnel. A success toast lists the nodes that received L3 config.

Current Limitations

• User deletion is not implemented in the current frontend/API path.
• Audit revert API exists, but currently only supports legacy route resources; the console only exposes diff viewing.
• Legacy /api/routes APIs still exist, but the current console workflow is L4 chains and L3 tunnels.
• The old dedicated TLS and ENC key pages have been merged into /gateway/credentials.
• Display REST/control endpoints in settings are local browser hints used for copyable config text. They do not change backend runtime configuration.

Pages

• Authentication
• Dashboard
• Nodes
• L3 Tunnels
• L4 Chains
• Port Management
• L4 Upstreams
• Security Credentials
• Audit Log
• Users
• Settings
• API-Only Features