Nexuma Documentation

Nexuma is a multi-node VPN and proxy management platform. It provides a central web panel, a control API, and node agents that run on VPN/proxy servers.

This documentation repository is self-contained. The examples below use published container images and do not require access to the application source repositories.

What Nexuma Provides

• Central management for users, tariffs, subscriptions, nodes, routing, and audit logs.
• Public subscription links for VPN clients.
• Per-user traffic limits, expiry, balance, and auto-renewal.
• Multi-node deployment with per-node protocol configuration.
• Supported subscription exports: v2ray, clash, and singbox.
• Supported protocols: VLESS, VMess, Trojan, Shadowsocks, HTTP, SOCKS, WireGuard, Hysteria, and MTProto.
• Routing rule sets, traffic blocking options, and node outbounds for proxy chains.
• External subscription sources that can be appended to user subscriptions.
• Telegram login, approval flow, and notifications when configured.

Main Components

Users and admins
       |
       v
Panel - web interface and public subscription page
       |
       v
Core  - API, state, subscription generation, node coordination
       |
       v
Nodes - VPN/proxy servers that apply configs and report usage

Quick Start

1. Deploy Core and Panel

Create a docker-compose.yml from the base example:

version: '3.9'

services:
  redis:
    image: redis:7-alpine
    container_name: nexuma-redis
    restart: unless-stopped
    volumes:
      - redis_data:/data
    networks:
      - nexuma

  core:
    image: nexuma/core:latest
    container_name: nexuma-core
    restart: unless-stopped
    environment:
      PORT: 3000
      GRPC_PORT: 3002
      DB_HOST: your-postgres-host
      DB_PORT: 5432
      DB_USER: postgres
      DB_PASSWORD: change-me
      DB_NAME: nexuma
      REDIS_HOST: redis
      REDIS_PORT: 6379
      JWT_SECRET: replace-with-long-random-secret
      JWT_REFRESH_SECRET: replace-with-another-long-random-secret
      JWT_EXPIRES_IN: 15m
      JWT_REFRESH_EXPIRES_IN: 7d
      CORS_ORIGINS: https://panel.example.com
    ports:
      - "3000:3000"
      - "3002:3002"
    depends_on:
      - redis
    networks:
      - nexuma

  panel:
    image: nexuma/panel:latest
    container_name: nexuma-panel
    restart: unless-stopped
    environment:
      NUXT_CORE_URL: http://core:3000
      NUXT_PUBLIC_API_BASE: /api
    ports:
      - "3010:3000"
    depends_on:
      - core
    networks:
      - nexuma

volumes:
  redis_data:

networks:
  nexuma:
    driver: bridge

Run:

docker compose up -d

Open http://your-server:3010.

2. Create the First Admin

Register the first user in the panel. Promote or seed an admin according to your deployment policy before exposing the system publicly.

3. Deploy a Node

In the panel, open Nodes and generate a registration code. Then deploy a node 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
      CORE_GRPC_URL: core.example.com:3002
      REGISTRATION_CODE: paste-one-time-code-here
      HEARTBEAT_INTERVAL_SEC: 30
    volumes:
      - node_data:/var/lib/vpnnode
    ports:
      - "3001:3001"
    cap_add:
      - NET_ADMIN

volumes:
  node_data:

Run:

docker compose up -d

After the node registers successfully, remove REGISTRATION_CODE and redeploy. Keep the node_data volume; it contains the persistent node auth key and local service state.

Documentation Index

• Core - control API, environment, Docker, public/user/admin API, and node-private API overview.
• Panel - operator UI, self-service UI, routes, environment, Docker, and API behavior.
• Node - node agent setup, registration, environment, Docker, local endpoints, and operations.
• Core API routes - detailed Core route table.
• Core private node routes - node-to-Core private API contract.

Security Checklist

• Replace all example secrets before production.
• Use HTTPS for public panel and Core endpoints.
• Restrict Core API exposure with firewall or reverse-proxy rules.
• Restrict node agent ports to trusted networks.
• Remove one-time node registration codes after successful registration.
• Rotate node auth keys when a node is rebuilt or compromised.
• Keep database and Redis inaccessible from the public internet.