VyManager

Enterprise-grade VyOS Router Management System

Modern web interface to make configuring, deploying and monitoring VyOS routers easier

Open Beta Community Release

Open beta release. Expect lower stability and bugs. This release provides a lot of structural improvements over the older legacy version. We now flexibly support all active VyOS versions, including rolling releases.

Skip to Quick Start

Join our Discord community to receive official updates

Give us a star to support us!

---

Screenshots

<img width="1911" height="862" alt="image" src="https://github.com/user-attachments/assets/b23d2eb2-32bc-4e01-9d62-7eefc76e1526" /> <img width="532" height="403" alt="image" src="https://github.com/user-attachments/assets/eb1070eb-4996-4669-a165-d555d191173c" /> <img width="1919" height="933" alt="image" src="https://github.com/user-attachments/assets/caf5c99d-3b13-4ed8-a917-f64dda914911" /> <img width="1919" height="933" alt="image" src="https://github.com/user-attachments/assets/2f883341-8d2c-4022-a33d-17f9a93e33a7" /> <img width="1919" height="935" alt="image" src="https://github.com/user-attachments/assets/0ef645db-7c62-4f07-8b00-309f81773b3a" />

---

Quick Start

Prerequisites

• Docker & Docker Compose installed on your host machine
• VyOS Router with REST API and GraphQL enabled (see Step 1)

---

Deployment Guide

Step 1: Enable the VyOS REST API

Before deploying VyManager, enable the REST API on your VyOS router(s).

Connect to your VyOS router via SSH and run:

# Enter configuration mode
configure

# Create an API key (replace YOUR_SECURE_API_KEY with a strong random key)
set service https api keys id vymanager key YOUR_SECURE_API_KEY

# Enable REST functionality (VyOS 1.5+ only)
set service https api rest

# Enable GraphQL (required for dashboard streaming)
set service https api graphql

# Set GraphQL authentication to use the API key defined above
set service https api graphql authentication type key

# Save and apply
commit
save
exit

Security Note: Keep your API key secure! You'll need it during the VyManager setup wizard.

GraphQL is required for the live dashboard cards (interface counters, system info, network speed graph, and WireGuard peers). All dashboard data is streamed via the VyOS GraphQL API using the same API key configured above.

Step 2: Create the project directory

Create a new directory for VyManager and navigate into it:

mkdir vymanager
cd vymanager

You will create two files inside this directory: docker-compose.yml and .env.

Step 3: Create the docker-compose.yml

Create a file named docker-compose.yml with the following contents:

services:
  postgres:
    image: postgres:16-alpine
    container_name: vymanager-postgres
    environment:
      POSTGRES_USER: vymanager
      POSTGRES_PASSWORD: CHANGE_ME_POSTGRES_PASSWORD
      POSTGRES_DB: vymanager
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped
    networks:
      - vymanager-network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U vymanager -d vymanager"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s

  backend:
    image: ghcr.io/community-vyprojects/vymanager-backend:beta
    container_name: vymanager-backend
    ports:
      - "8000:8000"
    env_file:
      - .env
    restart: unless-stopped
    networks:
      - vymanager-network
    depends_on:
      postgres:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/docs"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

  frontend:
    image: ghcr.io/community-vyprojects/vymanager-frontend:beta
    container_name: vymanager-frontend
    ports:
      - "3000:3000"
    env_file:
      - .env
    depends_on:
      backend:
        condition: service_healthy
      postgres:
        condition: service_healthy
    restart: unless-stopped
    networks:
      - vymanager-network

networks:
  vymanager-network:
    driver: bridge

volumes:
  postgres_data:
    driver: local

Step 4: Create the .env file

Create a file named .env in the same directory. Both the backend and frontend containers read from this single file.

You must change these values before starting:

1. POSTGRES_PASSWORD — Change this in both docker-compose.yml and DATABASE_URL below; they must match. Generate one with: openssl rand -hex 32
2. BETTER_AUTH_SECRET — Used to sign and verify session tokens; appears twice in the file (once for each service) and must be the same value in both places. Generate with: openssl rand -base64 32
3. SSH_ENCRYPTION_KEY — Used to encrypt stored SSH private keys at rest. Generate with: openssl rand -hex 32
4. BETTER_AUTH_URL / NEXT_PUBLIC_APP_URL — Replace <YOUR_SERVER_IP> with the IP or hostname users will open in their browser.
5. TRUSTED_ORIGINS — Comma-separated list of every URL users will access VyManager from.

# ── Backend ──────────────────────────────────────────────
# CHANGE_ME_POSTGRES_PASSWORD must match POSTGRES_PASSWORD in docker-compose.yml
DATABASE_URL=postgresql://vymanager:CHANGE_ME_POSTGRES_PASSWORD@postgres:5432/vymanager
FRONTEND_URL=http://frontend:3000

# CHANGE THIS — use a long random string (e.g. openssl rand -base64 32)
# Must match the BETTER_AUTH_SECRET value below — both services use this file
BETTER_AUTH_SECRET=Change-This-To-Something-Secret

# CHANGE THIS — use a long random hex string (e.g. openssl rand -hex 32)
SSH_ENCRYPTION_KEY=Change-This-To-A-Hex-String

# ── Frontend ─────────────────────────────────────────────
NODE_ENV=production
VYMANAGER_ENV=production

# Must be the same value as BETTER_AUTH_SECRET above
BETTER_AUTH_SECRET=Change-This-To-Something-Secret

# CHANGE THIS — set to the URL where users access VyManager in their browser
BETTER_AUTH_URL=http://<YOUR_SERVER_IP>:3000
NEXT_PUBLIC_APP_URL=http://<YOUR_SERVER_IP>:3000

# Internal Docker network URL — do not change unless you rename the backend service
BACKEND_URL=http://backend:8000

# CHANGE THIS — comma-separated list of every URL users will access VyManager from
# Example: http://192.168.1.50:3000,http://vymanager.lan:3000
TRUSTED_ORIGINS=http://<YOUR_SERVER_IP>:3000,http://localhost:3000

Tip: Generate a strong secret with: openssl rand -hex 32

Step 5: Start VyManager

From inside the vymanager directory, run:

docker compose up -d

Docker will pull the images, start PostgreSQL, wait for it to be healthy, then start the backend and frontend. This may take a minute on first run.

Check that all three containers are running:

docker compose ps

You should see vymanager-postgres, vymanager-backend, and vymanager-frontend all in a healthy / running state.

Step 6: Complete the Setup Wizard

1. Open your browser and navigate to http://<YOUR_SERVER_IP>:3000

2. The onboarding wizard will launch automatically on first visit:

   • Step 1: Create your admin account
   • Step 2: Create your first site (e.g., "Headquarters")
   • Step 3: Add your first VyOS instance
     • Name: Give it a friendly name
     • Host: Your VyOS router IP address
     • Port: 443 (default)
     • API Key: The key you created in Step 1
     • Version: Select your VyOS version (1.4 or 1.5)

3. Start Managing! You'll be automatically logged in and redirected to the dashboard.

---

Managing the Deployment

Common Docker Commands

# View logs (all services)
docker compose logs -f

# View logs for a single service
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f postgres

# Stop all services
docker compose down

# Restart all services
docker compose restart

# Restart a single service
docker compose restart backend

# Pull latest images and recreate containers
docker compose pull
docker compose up -d

# Remove everything including the database volume
docker compose down -v

Updating VyManager

When a new version is released, update by pulling the latest images:

cd vymanager
docker compose pull
docker compose up -d

Your database and configuration are preserved in the postgres_data volume.

---

Architecture Overview

Multi-Instance Management

VyManager uses a multi-instance architecture allowing you to manage multiple VyOS routers from a single interface:

• Sites: Logical groupings of VyOS instances (e.g., "Data Center 01", "Branch Office NYC")
• Instances: Individual VyOS routers within a site
• Role-Based Access: OWNER, ADMIN, and VIEWER roles per site
• Active Session: Connect to one instance at a time for configuration

Database-Driven Configuration

VyManager stores all instance configurations in a PostgreSQL database:

PostgreSQL Database
├── users           # User accounts
├── sites           # Site groupings
├── instances       # VyOS router instances
├── permissions     # User-site role mappings
└── active_sessions # Current connections

All VyOS instances are managed through the web UI — no hardcoded configuration.

---

Managing Multiple VyOS Instances

Adding More Sites

1. Navigate to Site Manager (click VyOS logo in sidebar)
2. Click "Add Site" button
3. Enter site name and description
4. Click "Create Site"

Adding Instances to a Site

1. In Site Manager, select a site from the list
2. Click "Add Instance" button
3. Fill in instance details:
   • Name: Friendly name for this router
   • Description: Optional notes
   • Host: IP address or hostname
   • Port: HTTPS port (default 443)
   • API Key: The key from VyOS configuration
   • Version: Select 1.4 or 1.5
   • Protocol