docs/node.md

Node

Agent that runs on each VPN server. Connects to Core, receives protocol configuration, manages the xray process, and reports traffic statistics.

Configuration

Edit the environment variables in docker-compose.node.yml:

Variable	Required	Description
CORE_URL	Yes	URL of the Core service (e.g. http://your-core-server:3000)
REGISTRATION_CODE	Once	One-time code generated in admin panel → Nodes
HEARTBEAT_INTERVAL_SEC	No	Heartbeat interval in seconds (default: 30)

Data directory is /var/lib/vpnnode and mounted as a Docker volume — all state (auth key, VPN configs, binaries) persists across container restarts automatically.

Registration

1. In the admin panel, open Nodes and generate a registration code.
2. Set CORE_URL and REGISTRATION_CODE in docker-compose.node.yml.
3. Run docker compose -f docker-compose.node.yml up -d.
4. Once the node appears as online in the panel, remove the REGISTRATION_CODE line.

Behaviour

• Sends a heartbeat to Core every 30 seconds; if Core reports a newer config revision, the node pulls it immediately.
• Core can also trigger an instant config pull by calling the node directly (e.g. on admin-initiated sync).
• Reports per-subscription traffic to Core every minute.
• On first start, automatically installs the latest xray release if not present.
• Updates GeoIP/Geosite files automatically every 12 hours.