Nodeboard Features Reference

Nodeboard is the operator-facing console for AeroNyx decentralized privacy nodes and related privacy network services.

Dashboard

The dashboard should summarize:

total registered nodes
online nodes
aggregate active sessions
encrypted traffic
encrypted packet forwarding
capacity warnings
recent events
MemChain or encrypted storage module status when enabled

Nodes

The Nodes area should support:

node registration
node status
region and capability metadata
heartbeat freshness
capacity fields
service configuration
safe maintenance visibility

Services

Services are layered so the first screen stays focused on decisions instead of raw diagnostics.

First-level Services should show:

commercial readiness
reporting node count
privacy protocol readiness
enabled service slots
attention count
rollout restart count
capacity risk summary
primary operator task

The Operations Workbench organizes detail reports into three lanes:

Operate: client placement, node capacity, and transport carriers.
Recover: Gateway DNS, restart and rollout, and service risks.
Inspect: service-layer readiness and full per-node readiness tables.

Details remain available without crowding the page:

IP pool capacity
used IPs
remaining IPs
CPU load
memory usage and total memory
resource-load capacity risk
disk capacity
max_connections
policy max_sessions
conntrack
file descriptors
packet drops
pps
bps
DNS status
transport metadata
MemChain readiness
encrypted storage readiness

This interaction model keeps Nodeboard usable for daily operations while still giving engineering teams the deep reports needed for incident response and rollout review.

Packet runtime telemetry

Nodeboard should expose Rust packet handler runtime health in node detail, not as a crowded first-level Services module.

The current UI location is:

Node Detail
Capacity panel
Stale Session Packets card

The card should help operators answer:

Did a Rust restart leave clients sending packets for stale process-local sessions?
Is the stale-session count historical, or still increasing?
Does this node need client reconnect review, drain review, or maintenance mode?

Expected backend contract:

text

data.nodes[].system.packet_runtime.reported
data.nodes[].system.packet_runtime.encrypted_vpn_packets
data.nodes[].system.packet_runtime.unknown_session_packets
data.nodes[].system.packet_runtime.active_sessions
data.nodes[].system.packet_runtime.unknown_session_status

Expected statuses:

clear
stale_after_restart
watch
unknown

This feature belongs in node detail because it is per-node evidence. Services may summarize fleet readiness later, but it should not become another first-level module unless it becomes a fleet-wide blocker.

Registration Codes

Registration Codes are the operator-facing onboarding workflow for decentralized privacy nodes.

The feature should support:

short-lived registration code generation
preview command generation through deploy/node/aeronyx-node.sh plan
one-command install generation through deploy/node/aeronyx-node.sh install --quick
post-install verification through deploy/node/aeronyx-node.sh health --json
AI assistant prompt generation for Codex, OpenClaw, Claude Code, Hermes, and similar terminal-capable agents
install stage timeline with plan, preflight, dependencies, repository, config, network, build, systemd, register, start, and completed
structured privacy-safe install detail chips such as command mode, repository path, branch, service, config path, failed phase, exit code, script version, host, OS, and architecture
failure-first chip ordering, so failed rows prioritize failed_phase and exit_code before lower-priority path fields
linked-node handoff after registration code consumption

This page should stay focused on onboarding. It should make the next operator action obvious without turning Services into a dense installer dashboard.

Privacy boundary: Registration Codes must never reveal registration secrets after expiration, private keys, API tokens, passwords, client public IPs, destinations, DNS contents, packet payloads, domains, URLs, browsing history, voucher secrets, chat plaintext, MemChain plaintext, encrypted storage plaintext, or wallet-level traffic.

Sessions

Sessions should show aggregate privacy network usage, not private user activity. The UI should avoid revealing destinations, domains, URLs, DNS contents, or packet payloads.

Events

Events should help operators diagnose service state:

registration events
heartbeat changes
service warnings
capacity risk
access code changes
billing state changes
MemChain sync warnings
encrypted storage pressure warnings

Private access codes

Private access codes are operator credentials for controlled access flows. They should be handled like secrets and not shared in public support channels.

Billing

Billing should connect commercial operation with transparent aggregate usage. It should not expose user-level browsing or message content.

MemChain and encrypted storage

When enabled, Nodeboard should show capability and health:

module status
encrypted object count
storage pressure
last checkpoint
sync state
verification status

The UI must not show plaintext memory records, decrypted chat logs, user storage contents, or keys.

Healthcheck Operator Action

Node control workflows should consume the Rust healthcheck operator_action summary when available. This field turns raw local diagnostics into one operator-facing recommendation while preserving the full checks[], runtime, capacity, local_vpn_health, and upgrade_status evidence for deeper review.

Recommended UI behavior:

first show the operator_action.title, status, and next_step
keep detailed checks behind node detail panels or runbook commands
treat critical as a node-level action blocker
treat warning as a commercial placement risk
keep Services first-level views focused on fleet health and link to node detail for evidence

The feature is designed for humans and AI assistants. It should help both answer: what is wrong, where did the conclusion come from, and what should be done next.

Heartbeat Operator Action

Nodeboard should prefer data.nodes[].system.operator_action when it is available from backend VPN observability. This field is produced by Rust /api/vpn/health, stored through heartbeat system_stats.vpn_health.operator_action, and exposed by the backend overview API.

Recommended node detail behavior:

use operator_action.status for tone
show operator_action.title and next_step before lower-level evidence
link the operator to the detailed panel referenced by operator_action.source
fall back to existing health/capacity/runtime cards when older decentralized privacy nodes have not upgraded yet

This keeps Services lean and moves node-specific evidence to node detail, while giving operators a clear first action.

Services vs Node Detail information architecture

Nodeboard uses a two-level operations model:

Services page: fleet readiness, capacity posture, policy health, restart readiness, command delivery, and short action routing.
Node Detail page: node-level capacity, Rust runtime, install status, upgrade workflow, recent operational events, runbook commands, health checks, and Rust-authored operator recommendations.

Rust-authored operator recommendation

Node Detail supports data.nodes[].system.operator_action with:

status: ok, info, warning, critical, or compatible future status strings
priority: machine-readable action priority
title: operator-facing summary
detail: evidence summary
next_step: recommended next action
source: Rust evidence source used for routing
privacy_boundary: optional privacy statement

The UI maps the recommendation to the Operator Actions hub and links to the most relevant detail panel. This avoids adding more first-level Services modules while still giving operators a direct path to remediation.

Related files:

Rust: /root/open/AeroNyx/crates/aeronyx-server/src/api/vpn_health.rs
Backend: /root/aeronyx/privacy_network/api/vpn_observability.py
Nodeboard types: /root/open/nodeboard/types/index.ts
Nodeboard UI: /root/open/nodeboard/app/dashboard/nodes/[id]/page.tsx
i18n: /root/open/nodeboard/lib/i18n/index.ts

Naming contract

Nodeboard user-facing labels should use AeroNyx privacy protocol language:

Dashboard operations card: AeroNyx Operations
Node health label: Healthy Protocol Nodes or localized equivalent
Traffic label: Encrypted Traffic or localized equivalent
Sessions / Events runbooks: reference AeroNyx Operations, not VPN Operations

This is a product-language rule only. It does not rename backend routes such as /api/privacy_network/vpn/overview/, because those routes are compatibility contracts consumed by the current Nodeboard, backend, and Rust telemetry pipeline.

Capacity recommendation contract

Node Detail -> Capacity renders structured capacity risk recommendations from Rust.

Contract path:

Rust: crates/aeronyx-server/src/api/vpn_health.rs
Backend: privacy_network/api/vpn_observability.py
Nodeboard type: types/index.ts -> VpnCapacityRiskSnapshot
Nodeboard UI: app/dashboard/nodes/[id]/page.tsx

Supported fields:

recommended_value: recommended target configuration
recommended_command: optional next command for the operator

The first-level Services page should continue to show only fleet-level capacity posture. Detailed recommendations belong on Node Detail so the commercial console stays scannable.

Commercial operations decisions

Nodeboard now treats operations as decisions, not raw telemetry.

Capacity Decision

Capacity Decision summarizes IP pool capacity, used IPs, remaining IPs, max_connections, policy max_sessions, conntrack, file descriptors, packet drops, pps, bps, and Rust service state. It produces a single recommendation such as expand IP pool, tune fd limits, tune conntrack, raise capacity policy, move traffic, restart after drain, or enter maintenance mode.

Incident Closure

Incident Closure groups related events and shows impact, recommended action, recovery state, repeated count, and affected node/session links. Operators should treat Open items as immediate work and Watch items as repeated reliability signals.

Quickstart command generation

Registration Codes generates a one-command install path:

clone or pull main -> preview plan -> install/register -> status -> healthcheck.

Operators should copy the Nodeboard command instead of manually combining lower-level scripts.