Development Guide

Status: Current

Last reviewed: 2026-05-13

Requirements

• Rust 1.88 or newer for nexus-agent.
• Node.js 20 or newer for nexus-frontend.
• Docker and Docker Compose.
• PostgreSQL client tools are useful for local debugging.

Repository Layout

NexusNet/
  nexus-backend/
  nexus-agent/
  nexus-frontend/
  nexus-docs/

Backend

Start backend dependencies and service:

cd /home/coder/NexusNet/nexus-backend
docker compose up --build

The compose file starts:

• nexus-backend
• postgres
• postgres-timescale
• redis
• optional cloudflared

Current compose maps:

• PostgreSQL: localhost:5432
• TimescaleDB: localhost:5433
• Redis: localhost:6379
• Agent control: REALITY listener from NEXUS_REALITY_LISTEN_ADDR

The backend process is configured with REST_LISTEN_ADDR=0.0.0.0:8081, but the current compose file does not publish 8081. Publish it when testing REST through Docker, or run the backend locally.

Useful local commands:

cd /home/coder/NexusNet/nexus-backend
cargo check
cargo test

Agent

Build and run the two-node local agent compose:

cd /home/coder/NexusNet/nexus-agent
docker compose up --build

The agent compose uses host networking and creates:

• nexus-agent-hk
• nexus-agent-sg

Useful local commands:

cd /home/coder/NexusNet/nexus-agent
cargo check -p nexus-agent
cargo test -p nexus-agent quic::tests --lib
cargo test -p quinn-reality

QUIC REALITY iperf smoke tests are ignored by default and should be run explicitly when validating performance work.

Frontend

cd /home/coder/NexusNet/nexus-frontend
npm install
npm run dev

Current dashboard routes include:

• /dashboard
• /nodes
• /gateway/l3-networks
• /gateway/l4-chains
• /gateway/l4-upstreams
• /gateway/credentials
• /audit
• /settings
• /settings/users

Docs

cd /home/coder/NexusNet/nexus-docs
npm install
npm run dev
npm run build

This repository is a VitePress site. .vitepress/config.mts owns the web navigation and language selector. SUMMARY.md remains a readable Markdown index.

Frontend UI conventions are documented in Frontend Development.