nyxmael/nyxguardmanager repository overview

⁠NyxGuard Manager

Your applications. Your infrastructure. One security workspace.

A self-hosted reverse proxy with application protection, traffic intelligence,
WireGuard access and operational diagnostics.

Install⁠ · Update⁠ · VPN⁠ · Website⁠ · Documentation⁠ · Community⁠

⁠Overview

Manage HTTPS applications, certificates, access policies, traffic and remote VPN sites from one interface. Configuration, certificates and operational history stay on your infrastructure.

Current release · 5.0.13 uses a conventional host-managed Docker update: replace application code, reuse persistent storage, run versioned migrations, and verify readiness. MariaDB and its volume remain intact on successful upgrades. Manager uses VPN Agent 5.0.2 and schema 46.

Read the release notes⁠ · Browse the changelog⁠

⁠Installation

On a fresh supported Ubuntu or Debian host with systemd and curl available:

As root, including minimal Debian without sudo:

curl -fsSL https://raw.githubusercontent.com/NyxCloudRO/NyxGuardManager/main/install.sh | bash

As an ordinary user with sudo privileges:

curl -fsSL https://raw.githubusercontent.com/NyxCloudRO/NyxGuardManager/main/install.sh | sudo bash

The installer checks privileges and prepares Docker/Compose dependencies, persistent storage and automatic startup. If curl or certificate trust is missing, follow the prerequisites and manual installation guide⁠. Existing installations use the updater.

Open https://<your-host>:8443 and complete the setup wizard. The initial self-signed certificate requires browser confirmation. The installer prepares Docker/Compose, persistent storage and automatic startup. Review the requirements below, especially TUN access if you need VPN.

For existing installations, use the supported update procedure⁠.

⁠Main features

Professional Support is optional. Signed entitlements are verified locally and stored in an encrypted persistent vault. Licensing failure does not disable core proxy management or security controls. This release retains safe licensing and certificate errors, administrative audit signal and compact Protected Apps. Persistent diagnostics and bounded Recent problems remain available. Database-down failures use a safe log fallback. Support bundles select structured fields and redact sensitive values; they are not raw configuration/log archives.

⁠Requirements

Actual resource requirements depend on the number of protected applications (Proxy Hosts), traffic volume, enabled WAF and VPN features, and the configured log retention period (in months). Longer retention periods and higher traffic volumes may require additional CPU, RAM, and disk space.

These tiers are sizing targets, not validated capacity guarantees. Storage covers normal operation; allow additional free space for backups, database growth and upgrades, as well as space for the host OS and Docker image cache. Before an upgrade, the updater requires free space on the backup filesystem of at least three times the current persistent-data size plus 2 GiB. Retained backups and larger image downloads may require more.

Network: host access to Docker registries and certificate services; inbound TCP 80/443 for public applications; administration on HTTPS 8443.

⁠Supported operating systems

Support carries forward independently of hotfix retesting. The installation and compatibility guide⁠ records the evidence and configuration limits; 5.0.13 validation coverage⁠ describes the focused release tests. Historical family labels do not certify every point release.

For 5.0.12, native Ubuntu 24.04.5 fresh installations passed with stock installer deadlines, including Manager-only without TUN and Manager plus Agent with TUN. Required-VPN rejection, later Agent activation and same-version no-op were also checked.

The installer requires Ubuntu or Debian, apt-get and a running systemd host; it prepares Docker/Compose dependencies. VPN also requires usable host TUN and a reachable WireGuard endpoint. Restricted guests without TUN can run Manager and MariaDB without VPN. Other distributions and versions outside this matrix have no established official support; manual Docker deployment is an evaluation path, not a support guarantee.

⁠Docker deployment

The normal installer deploys Manager and MariaDB, adding the compatible VPN Agent when TUN is usable. Data uses persistent Docker volumes; systemd provides automatic startup. The administration port is HTTPS 8443, and proxied applications use TCP 80/443.

HTTP-01 certificates need public inbound TCP 80. DNS challenges need the provider's credentials. Certbot initialization and Cloudflare plugin discovery remain supported. Corrected wildcard/apex Cloudflare issuance was observed on an existing installation; HTTP-01 and renewal workflows were exercised with controlled fixtures. New live staging issuance was not performed. Protected Apps are Proxy Hosts with WAF enabled.

services:
  nyxguard-manager:
    container_name: nyxguard-manager
    image: nyxmael/nyxguardmanager:5.0.13
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "8443:8443"
    environment:
      TZ: "${TZ:-UTC}"
      PUID: "${PUID:-1000}"
      PGID: "${PGID:-1000}"
      DB_MYSQL_HOST: "db"
      DB_MYSQL_PORT: "3306"
      DB_MYSQL_USER: "${DB_MYSQL_USER:-nyxguard}"
      DB_MYSQL_PASSWORD: "${DB_MYSQL_PASSWORD}"
      DB_MYSQL_NAME: "${DB_MYSQL_NAME:-nyxguard}"
      SKIP_CERTBOT_OWNERSHIP: "true"
      DISABLE_IPV6: "${DISABLE_IPV6:-false}"
      NYXCLOUD_LICENSE_VAULT_KEY_PATH: "/run/nyxguard-licensing/vault.key"
      NYXCLOUD_AUTHORITY_URL: "https://licensing.nyxcloud.ro"
      NYXCLOUD_SUPPORT_URL: "https://support-storage.nyxcloud.ro"
      NYXGUARD_VPN_AGENT_URL: "http://127.0.0.1:3198"
      NYXGUARD_VPN_AGENT_TOKEN_PATH: "/run/nyxguard-vpn-auth/token"
      # Persistent access-portal session. Chromium caps persistent cookies at 400 days.
      NYXGUARD_ACCESS_SESSION_TTL_SEC: "34560000"
    # Manager readiness is inherited from the accepted image.
    group_add:
      - "${DOCKER_SOCK_GID:?Set DOCKER_SOCK_GID to the numeric GID of /var/run/docker.sock}"
    volumes:
      - nyxguard_data:/data
      - nyxguard_letsencrypt:/etc/letsencrypt
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /etc/localtime:/etc/localtime:ro
      - /proc/1/net/arp:/host/proc/net/arp:ro
      - nyxguard_vpn_auth:/run/nyxguard-vpn-auth:ro
      - /var/lib/nyxguard-licensing/vault.key:/run/nyxguard-licensing/vault.key:ro
    depends_on:
      - db

  vpn-client-agent:
    container_name: nyxguard-vpn-agent
    image: nyxmael/nyxguardmanager-vpn-agent:5.0.2
    restart: unless-stopped
    network_mode: "service:nyxguard-manager"
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    environment:
      NYXGUARD_BACKEND_UID: "${PUID:-1000}"
    volumes:
      - nyxguard_vpn:/var/lib/nyxguard-vpn
      - nyxguard_vpn_auth:/run/nyxguard-vpn-auth
      - /etc/localtime:/etc/localtime:ro
    depends_on:
      nyxguard-manager:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "node", "-e", "const fs=require('fs');fetch('http://127.0.0.1:3198/status',{headers:{'X-NyxGuard-VPN-Token':fs.readFileSync('/run/nyxguard-vpn-auth/token','utf8').trim()}}).then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s

  db:
    container_name: nyxguard-db
    image: jc21/mariadb-aria:latest
    restart: unless-stopped
    environment:
      TZ: "${TZ:-UTC}"
      MYSQL_ROOT_PASSWORD: "${MYSQL_ROOT_PASSWORD}"
      MYSQL_DATABASE: "${DB_MYSQL_NAME:-nyxguard}"
      MYSQL_USER: "${DB_MYSQL_USER:-nyxguard}"
      MYSQL_PASSWORD: "${DB_MYSQL_PASSWORD}"
    volumes:
      - nyxguard_db:/var/lib/mysql
      - /etc/localtime:/etc/localtime:ro

volumes:
  nyxguard_data:
    name: nyxguard_data
  nyxguard_letsencrypt:
    name: nyxguard_letsencrypt
  nyxguard_db:
    name: nyxguard_db
  nyxguard_vpn:
    name: nyxguard_vpn
  nyxguard_vpn_auth:
    name: nyxguard_vpn_auth

TZ=UTC
PUID=1000
PGID=1000
DB_MYSQL_USER=nyxguard
DB_MYSQL_NAME=nyxguard
DB_MYSQL_PASSWORD=CHANGE_ME_STRONG_PASSWORD
MYSQL_ROOT_PASSWORD=CHANGE_ME_STRONG_ROOT_PASSWORD

chmod 600 .env
nyx_socket_gid="$(stat -c %g /var/run/docker.sock)"
sed -i "s/^PGID=.*/PGID=${nyx_socket_gid}/" .env
printf 'DOCKER_SOCK_GID=%s\n' "$nyx_socket_gid" >> .env
install -d -m 0700 /var/lib/nyxguard-licensing
sh -c 'test ! -e /var/lib/nyxguard-licensing/vault.key && test ! -L /var/lib/nyxguard-licensing/vault.key && umask 077 && set -C && head -c 32 /dev/urandom > /var/lib/nyxguard-licensing/vault.key'
chown "1000:${nyx_socket_gid}" /var/lib/nyxguard-licensing /var/lib/nyxguard-licensing/vault.key
chmod 0600 /var/lib/nyxguard-licensing/vault.key

docker compose --env-file .env up -d

⁠Updates and recovery

As root:

curl -fsSL https://raw.githubusercontent.com/NyxCloudRO/NyxGuardManager/main/update.sh | bash

As an ordinary sudo-enabled user:

curl -fsSL https://raw.githubusercontent.com/NyxCloudRO/NyxGuardManager/main/update.sh | sudo bash

The updater identifies the installed and latest stable published versions, asks for confirmation, pauses services to verify a complete recovery backup, downloads official images, and replaces Manager using the existing Compose configuration. It restarts the same MariaDB container and reuses the same named volumes, database credentials, licensing key, certificates and VPN state. An installed Agent is recreated only to attach it to Manager's new network namespace, using the release's compatible official Agent image. No temporary database or replacement application stack is created.

Database migrations run through the application's normal startup. Health, migration completion, durable configuration records and storage identities must pass before success is committed. A failed download simply restarts the unchanged installation. A failure after application replacement restores the verified pre-migration data and previous application. A repeated invocation on the current version makes no changes.

Use the current main command above. The 5.0.13 release asset contains the qualified self-contained updater. Historical 5.0.10 assets retain their original limitations.

See installation and update architecture⁠ for the persistent storage map, maintenance downtime, version pinning, supported topology and backup requirements. Independent backups remain recommended. Advanced restoration and historical 4.x transitions are documented separately in advanced recovery⁠. The in-app update action directs administrators to the host command.

⁠VPN Client and VPN Agent

Import WireGuard profiles in Settings → VPN Client. The separate VPN Agent 5.0.2 manages interfaces and routes in Manager's network namespace. Site controls expose connection state, handshakes, counters and connectivity checks. Keep Manager and Agent together through restarts. Standard full-tunnel profiles work without subnet overrides; optional remote networks restrict a tunnel. Existing local routes and replies to incoming Manager connections retain their original path. Only one managed full tunnel per IP family can be connected at a time.

Installation is capability-based: usable read/write TUN enables Agent installation; unavailable TUN leaves Manager and MariaDB operational and clearly reports VPN Agent pending — TUN unavailable. The installer attempts safe guest-side device preparation, but it does not configure a hypervisor.

⁠Proxmox LXC: TUN and VPN Agent

Manager/database can run without TUN; VPN Agent needs usable read/write /dev/net/tun. NyxGuard does not configure the Proxmox host automatically.

Follow the numbered Proxmox LXC/TUN setup and same-version repair guide⁠. It separates Proxmox host and LXC guest commands, verifies the target CTID/hostname/IP, backs up its configuration, selects a free devN slot and uses supported device passthrough. Never overwrite an occupied slot or convert the LXC to privileged. Restart only the selected LXC if required.

After guest TUN is usable, follow Agent activation⁠ using the existing Compose service. It preserves Manager/database data and uses compatible VPN Agent 5.0.2. The old release-pinned repair helper is historical guidance only. Then check health and Settings → VPN Client, a recent handshake and actual permitted-destination connectivity. TUN presence alone does not prove a working VPN.

See the VPN Client guide⁠ for profiles, allowed networks and remote-peer troubleshooting, or the website walkthrough⁠.

⁠Quick health checks

curl -kI https://127.0.0.1:8443/
curl -ksS https://127.0.0.1:8443/api/ | jq
docker ps
docker exec nyxguard-manager node /app/internal/readiness-probe.mjs
docker logs --tail=100 nyxguard-manager
docker logs --tail=100 nyxguard-vpn-agent

Expect healthy Manager and DB, plus the VPN Agent on TUN-capable hosts. HTTP 200 alone does not prove database readiness, data preservation or working VPN sites. The Settings VPN Client tab shows Agent availability, site controls, handshakes, traffic and ping results. Connect controls appear in both the selected site and disconnected site cards; automatic reconnect starts after the first successful connection. Network/tunnel overlaps and local-network collisions are rejected.

⁠Security

Use strong credentials, limit access to the administration interface and keep independent database and volume backups. Store DNS-provider and other integration secrets securely. The licensing vault key is persistent: preserve it through updates and recovery.

The supported deployment runs application services under the configured PUID/PGID; Manager has Docker socket group access for metrics and diagnostics. Normal upgrades run on the host. Socket access is powerful even with a read-only bind; expose the administration interface only to trusted users. VPN Agent needs its documented NET_ADMIN capability and TUN device. Review VPN routing and firewall guidance⁠ before connecting a profile.

Professional Support is optional and does not disable core proxy or security features when licensing is unavailable. Generated support bundles use structured redaction; review an exported bundle before sharing it.

⁠Documentation and support

Use GitHub releases⁠, the community⁠ and NyxCloud⁠ for release and operational guidance. Professional Support adds Diagnostics & Support and Support ID workflows. Support development⁠.

Created by Vlad-Eusebiu Cardei to bring security, observability and predictable day-to-day operations into the same local-first proxy workflow. Project links: NyxCloud⁠, BillCore⁠ and Community⁠. Contact: [email protected]⁠ · [email protected]⁠.

⁠License

NyxGuard Manager is free to use in internal personal and commercial environments under the NyxGuard Manager Proprietary License (NMPLA). Modification, redistribution, resale and third-party hosting are not permitted. Read the full license⁠.

Changelog⁠ · Release source map⁠

⁠Publication review

Source and release publication follow the public-source review policy⁠, including dependency, version, artifact and privacy checks.