NexusNet

Appearance

Architecture Overview ​

Status: Current

Last reviewed: 2026-05-10

Repositories ​

NexusNet is currently split into three code repositories plus this docs repository:

  • nexus-backend: Rust control plane, REST API, gRPC AgentService, PostgreSQL storage, route deployment logic, credentials, and dashboard data.
  • nexus-agent: Rust node agent, Pingora/L4 gateway, TCP/UDP forwarding, Noise/REALITY credentials, TCP REALITY, QUIC REALITY, QUIC DATAGRAM, and metrics.
  • nexus-frontend: Next.js dashboard for nodes, L4 chains, upstreams, TLS, encryption credentials, audit, and settings.
  • nexus-docs: canonical documentation.

Control Plane ​

The control plane is implemented by nexus-backend.

Main responsibilities:

  • REST API under /api.
  • JWT authentication and RBAC.
  • PostgreSQL schema migrations.
  • Node registration and heartbeat over gRPC.
  • Agent config streaming with PingoraConfig.
  • L4 chain persistence and deployment.
  • Upstream, TLS certificate, and encryption credential management.
  • Dashboard stats and audit log APIs.

Current backend runtime:

  • Rust edition 2024.
  • Axum for REST.
  • Tonic for gRPC.
  • SQLx with PostgreSQL.
  • Redis is present in compose for supporting services/rate-limiting evolution.

Agent Plane ​

The agent is implemented by nexus-agent.

Main responsibilities:

  • Register with the backend over gRPC.
  • Maintain heartbeat and receive config streams.
  • Run in-process gateway listeners for TCP, UDP, TLS, REALITY, and QUIC REALITY paths.
  • Apply TcpProxyRule, UdpRule, QuicRule, upstream clusters, and TLS certificates from backend config.
  • Report metrics snapshots.

Important agent modules:

  • src/gateway/mod.rs: gateway orchestration and tests.
  • src/gateway/udp.rs: UDP session forwarding, Noise, and QUIC REALITY DATAGRAM upstream path.
  • src/gateway/tls.rs: TLS handling.
  • src/gateway/crypto.rs: Noise/ENC helpers.
  • src/gateway/quic.rs and src/gateway/quic/*: QUIC REALITY listener, client pool, server handshake, stream forwarding, DATAGRAM forwarding, and metrics.
  • crates/reality-core: REALITY/TLS primitives.
  • crates/reality-io: TCP REALITY stream/session helpers.
  • crates/quic-core: internal QUIC packet, crypto, frame, and HTTP/3 helpers.

Frontend ​

The frontend is implemented by nexus-frontend.

Current dashboard pages:

  • Login.
  • Dashboard.
  • Nodes.
  • Gateway L4 chains.
  • Gateway L4 upstreams.
  • Gateway TLS.
  • Gateway encryption credentials.
  • Audit.
  • Settings and users.

Current Data Plane ​

Current supported or actively implemented paths include:

  • TCP over TCP RAW.
  • TCP over TCP TLS.
  • TCP over TCP REALITY.
  • UDP over UDP RAW.
  • UDP over UDP Noise.
  • TCP over QUIC REALITY.
  • UDP over QUIC REALITY DATAGRAM.

Planned paths are tracked in Transport Composition.

L3 Direction ​

Layer 3 work is planned as L3PTP REALITY:

  • TUN/netdevice-facing L3 tunnel semantics.
  • IP packets over QUIC REALITY DATAGRAM.
  • Reliable control plane for route, MTU, and state.
  • Future kernel DCO path for high-throughput true QUIC REALITY DATAGRAM.

See:

Last updated:

NexusNet documentation

Copyright © 2026 NexusNet