docs/node.md

Node

Node is the agent installed on each VPN/proxy server. It registers with Core, receives configuration revisions, applies local services, reports usage, and exposes authenticated runtime actions.

This page is public operator documentation. It describes setup, behavior, environment variables, Docker deployment, and the node HTTP API without requiring source-code access.

Capabilities

• One-time registration with Core.
• Persistent auth key storage.
• Config sync by revision.
• Xray install, restart, validation, GeoIP update, and key generation.
• MTProto install and restart.
• Nginx masking site management.
• System status reporting with CPU, RAM, disk, network, and process state.
• Heartbeat reporting.
• Per-user and per-subscription traffic reporting.
• Outbound traffic reporting for proxy chains.
• Session event reporting.
• Runtime error reporting.
• Crash watchdog for local services.

Environment Variables

Variable	Required	Default	Description
PORT	No	3001	Local node agent HTTP port.
NODE_ENV	No	development	Runtime mode.
CORE_URL	Yes	http://localhost:3000	Core API URL reachable from the node server.
REGISTRATION_CODE	First start only	empty	One-time node registration code generated in the panel.
NODE_AUTH_KEY	No	empty	Optional fallback auth key when no key file exists.
HEARTBEAT_INTERVAL_SEC	No	30	Heartbeat interval in seconds.

Persistent state is stored under /var/lib/vpnnode.

Keep this directory on a persistent Docker volume. It contains the auth key, generated configs, binaries, stats state, and masking-site files.

Docker Compose

Create a docker-compose.yml on the VPN/proxy server:

version: '3.9'

services:
  node:
    image: nexuma/node:latest
    container_name: nexuma-node
    restart: unless-stopped
    environment:
      PORT: 3001
      CORE_URL: https://core.example.com
      REGISTRATION_CODE: paste-one-time-code-here
      HEARTBEAT_INTERVAL_SEC: 30
    volumes:
      - node_data:/var/lib/vpnnode
    ports:
      - "3001:3001"
      # Add protocol ports here, for example:
      # - "443:443"
      # - "443:443/udp"
    cap_add:
      - NET_ADMIN
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://localhost:3001/health || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s

volumes:
  node_data:

Run:

docker compose up -d

After successful registration, remove REGISTRATION_CODE and redeploy:

docker compose up -d

Registration

1. In the panel, open Nodes.
2. Generate a registration code.
3. Set CORE_URL and REGISTRATION_CODE on the node server.
4. Start the node container.
5. Wait until the node appears as registered.
6. Remove REGISTRATION_CODE.
7. Keep the node_data volume for future restarts.

If the persistent volume is deleted, the node loses its auth key and must be registered again or started with NODE_AUTH_KEY.

Local HTTP API

Public:

Method	Route	Purpose
GET	/health	Health check.

All other routes require x-node-auth-key.

Method	Route	Purpose
GET	/node/status	Runtime status and resource usage.
POST	/node/apply-config	Trigger config pull and apply.
POST	/node/xray/restart	Restart Xray.
POST	/node/xray/install	Install an Xray version.
POST	/node/geoip/update	Update GeoIP/geosite files.
POST	/node/crypto/x25519	Generate X25519 keys.
POST	/node/crypto/mldsa65	Generate an ML-DSA-65 seed.
POST	/node/mtproto/restart	Restart MTProto processes.
POST	/node/mtproto/install	Install an MTProto version.
GET	/node/nginx/sites	List masking sites.
GET	/node/nginx/sites/:domain	Get one masking site.
PUT	/node/nginx/sites	Replace masking sites.
PUT	/node/nginx/site	Upsert one masking site.
GET	/node/nginx/site	Get current masking site status.
DELETE	/node/nginx/sites/:domain	Delete one masking site.
DELETE	/node/nginx/site	Delete current masking site.
POST	/node/nginx/restart	Restart nginx.

These endpoints are intended to be called by Core. Protect the agent port with firewall rules or private networking.

Config Sync

• The node keeps the latest applied revision locally.
• Core can ask the node to apply config immediately.
• Heartbeat responses can also request sync.
• The node pulls the latest config from Core.
• If config apply succeeds, the node confirms the applied revision.
• If config apply fails, the node reports an error and keeps the previous valid config where possible.

Traffic and Events

The node reports:

• user traffic
• subscription traffic attribution
• per-protocol usage
• outbound usage
• online/offline session events
• service crash and config errors

Traffic is flushed periodically. If reporting fails temporarily, the node keeps pending stats for the next flush where possible.

Status Output

GET /node/status returns operational status including:

• system uptime
• CPU usage and core count
• RAM usage
• disk usage
• network transfer rates and totals
• Xray running state and uptime
• MTProto process state and connection counts

Operations

• Use node sync from the panel after changing protocols, routing, or outbounds.
• Open every configured inbound port in Docker and the server firewall.
• Keep /var/lib/vpnnode persistent.
• Keep the node agent API private.
• Remove one-time registration codes after registration.
• Rotate auth keys when moving or rebuilding a server.