VyManager

Multi-tenant network management platform to configure, deploy, and monitor VyOS instances across multiple sites.

Quick Start · Documentation · Discord · Troubleshooting

Give us a ⭐ star to support us❤️

📖 Table of Contents

About VyManager
Features
Screenshots
Quick Start
Prerequisites
Installation
- Automated Script (Linux)
- Docker Setup
Configuration
Post‑Installation Setup Wizard
Managing Your Deployment
Managing Multiple VyOS Instances
Version‑Aware Architecture
Tech Stack
Development / Manual Setup
Security Considerations
AI Integration with VyMCP
Troubleshooting
Contributing
License
Support

🚀 About VyManager

VyManager is an open‑source, enterprise‑grade control plane for VyOS routers. It provides a modern web interface to manage multiple instances across different sites, with role‑based access control, live dashboards, and configuration deployment – all from a single pane of glass.

Multi‑site – organise routers into logical sites (e.g., datacenters, branch offices).
Version‑aware – supports VyOS 1.4, 1.5, and rolling releases.
Secure – API‑key authentication, encrypted SSH credentials, and fine‑grained permissions.
Extensible – built with Next.js, FastAPI, and PostgreSQL.

✨ Features

Centralised Management – add, remove, and configure VyOS instances from one UI.
Live Dashboards – real‑time interface counters, system info, network graphs, and WireGuard peers via GraphQL.
Role‑Based Access Control – OWNER, ADMIN, VIEWER per site.
Multi‑Version Support – automatically adapts features based on the connected VyOS version.
Docker‑First Deployment – runs anywhere with Docker Compose.
Light, Dark & Custom Themes – choose what suits you.

🖼️ Screenshots

User Interface supports Light, Dark and Custom themes.

⚡ Quick Start

The fastest way to get VyManager running is with our automated install script (Linux only) or the manual Docker Compose method.

Before you begin, make sure your VyOS routers are API‑ready – see the Prerequisites section below.

Documentation: https://docs.vyprojects.org/
Community: Discord

📋 Prerequisites

Regardless of which installation method you choose, you must first prepare your VyOS routers.

1. Docker & Docker Compose (for Docker setup)

If you use the automated script, it will install Docker and Docker Compose for you.
If you prefer Docker setup, ensure Docker and Docker Compose (v2) are installed on your host.

2. Enable the VyOS REST API and GraphQL

On each VyOS router you want to manage, SSH in and run:

configure
set service https api keys id vymanager key YOUR_SECURE_API_KEY
set service https api rest
set service https api graphql
set service https api graphql authentication type key
commit
save
exit

Important

GraphQL is required for live dashboard data.
The API key you set here will be used in VyManager when adding the instance.
Keep this key secure – it grants full access to the router’s API.

Once these prerequisites are satisfied, proceed with your preferred installation method below.

📦 Installation

Automated Script (Linux)

Important

The install script supports Ubuntu/Debian, Fedora, CentOS/RHEL, Arch Linux, and openSUSE. It automatically installs Docker, Docker Compose, and pulls the VyManager stack.

Run the following command as root or a user with sudo privileges:

wget https://raw.githubusercontent.com/Community-VyProjects/VyManager/beta/install.sh && bash install.sh

The script will:

Check for Docker & Docker Compose, install them if missing.
Create a vymanager directory with a pre‑populated .env and docker-compose.yml.
Start all containers.
Show you the access URL.

Note

Your VyOS routers must already have the REST API and GraphQL enabled (see Prerequisites). The script does not configure your routers – only VyManager itself.

Docker Setup

Prerequisites (already covered above)

Docker and Docker Compose (v2) installed.
VyOS routers with the REST API and GraphQL enabled.

1. Create the Project Directory

mkdir vymanager && cd vymanager

2. Create `docker-compose.yml`

Copy the docker-compose.yml from the repository, or use the snippet below:

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"
    volumes:
      - ./certs:/usr/local/share/ca-certificates/custom:ro
    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

3. Create the `.env` File

Create a .env file in the same directory. You must change the following values:

Variable	Description	Generate with
`POSTGRES_PASSWORD`	Database password (must match in `DATABASE_URL`)	`openssl rand -hex 32`
`BETTER_AUTH_SECRET`	Session token secret (must be the same in both places in the file)	`openssl rand -base64 32`
`SSH_ENCRYPTION_KEY`	Encryption key for SSH private keys at rest	`openssl rand -hex 32`
`BETTER_AUTH_URL` / `NEXT_PUBLIC_APP_URL`	The URL users will use to access VyManager	e.g., `http://192.168.1.50:3000`
`TRUSTED_ORIGINS`	Comma‑separated list of all allowed origins	e.g., `http://192.168.1.50:3000,http://localhost:3000`

Example .env (replace placeholders):

# Shared
BETTER_AUTH_SECRET=Change-This-To-Something-Secret

# Backend
DATABASE_URL=postgresql://vymanager:CHANGE_ME_POSTGRES_PASSWORD@postgres:5432/vymanager
FRONTEND_URL=http://frontend:3000
SSH_ENCRYPTION_KEY=Change-This-To-A-Hex-String

# Frontend
NODE_ENV=production
VYMANAGER_ENV=production
BETTER_AUTH_URL=http://<YOUR_SERVER_IP>:3000
NEXT_PUBLIC_APP_URL=http://<YOUR_SERVER_IP>:3000
BACKEND_URL=http://backend:8000
TRUSTED_ORIGINS=http://<YOUR_SERVER_IP>:3000,http://localhost:3000

Warning

Never commit the .env file to version control. Keep your secrets safe.

4. Start VyManager

docker compose up -d

Wait a minute for all services to become healthy, then open your browser to http://<YOUR_SERVER_IP>:3000.

⚙️ Configuration

Custom CA Certificates

If your VyOS routers use certificates signed by a private CA, you can add your CA certificates to the backend container:

Create a certs directory next to your docker-compose.yml:
```
mkdir certs
```
Place your PEM‑encoded .crt files inside:
```
cp /path/to/my-ca.crt ./certs/
```
Restart the backend:
```
docker compose restart backend
```

Note

All .crt files in that directory will be automatically imported on startup.

🧭 Post‑Installation Setup Wizard

On first visit, the onboarding wizard will guide you through:

Create an admin account – your first user.
Create your first site – e.g., "Headquarters".
Add a VyOS instance – provide the host, port, API key, and version.

After completing the wizard, you’ll be logged in and redirected to the dashboard.

🛠️ Managing Your Deployment

Updating VyManager

Run the update from the directory containing your docker-compose.yml file. For installations created by the automated script, this is /opt/vymanager:

cd /opt/vymanager
docker compose pull && docker compose build --no-cache && docker compose up -d --force-recreate

This pulls the latest images, rebuilds the local services without using cached layers, and recreates the containers. Your PostgreSQL data remains in the postgres_data volume. If you created the deployment manually, run the same command from your project directory instead.

Common Docker Commands

# View logs
docker compose logs -f

# Stop all services
docker compose down

# Restart
docker compose restart

# Pull latest images and restart services
docker compose pull
docker compose up -d

# Remove everything (including database volume)
docker compose down -v

🗂️ Managing Multiple VyOS Instances

Adding More Sites

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

Adding Instances to a Site

In Site Manager, select a site from the list
Click "Add Instance" button
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: HTTPS (recommended) or HTTP
Click "Complete Setup"

Connecting to an Instance

Navigate to Site Manager
Select a site
Click "Connect" on any instance card
VyManager will test the connection, verify API credentials, and redirect you to the dashboard
You can now manage that VyOS router!

Switching Between Instances

Click "Disconnect Instance" in the sidebar
You'll return to Site Manager
Connect to a different instance

🧩 Version‑Aware Architecture

VyManager supports multiple VyOS versions (1.4, 1.5+) using a version‑aware backend architecture.

How It Works

The backend uses a three‑layer architecture:

Routers (API Endpoints)
    ↓
Builders (Batch Operations)
    ↓
Mappers (Version‑Specific Commands)
    ↓
VyOS Device (1.4 or 1.5)

Every feature exposes a /capabilities endpoint that tells the frontend which features are available for the connected VyOS version. The frontend conditionally shows/hides features based on these capabilities.

Note

This design ensures that VyManager remains compatible with future VyOS releases without requiring major rewrites.

🧰 Tech Stack

Frontend

Framework: Next.js 16 (App Router)
Language: TypeScript
Styling: Tailwind CSS v4
UI Components: shadcn/ui
Icons: Lucide React
Authentication: Better‑auth
State Management: Zustand
Database ORM: Prisma

Backend

Framework: FastAPI
Language: Python 3.11+
VyOS SDK: pyvyos (custom)
Database: PostgreSQL
DB Driver: asyncpg

Infrastructure

Container: Docker & Docker Compose
Database: PostgreSQL 16
Container Registry: GitHub Container Registry (ghcr.io)

👨‍💻 Development / Manual Setup

If you want to contribute or run VyManager from source, follow the instructions below.

Frontend Development

cd frontend

# Install dependencies
npm install

# Run dev server (with hot reload)
npm run dev

# Type check
npm run type-check

# Lint
npm run lint

# Build for production
npm run build

Backend Development

cd backend

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run with auto-reload
uvicorn app:app --reload --host 0.0.0.0 --port 8000 --proxy-headers

# View API docs
# Navigate to http://localhost:8000/docs

Database Migrations

cd frontend

# Generate migration after schema changes
npx prisma migrate dev --name migration_name

# Apply migrations
npx prisma migrate deploy

# View database
npx prisma studio

🔒 Security Considerations

Always change default secrets (BETTER_AUTH_SECRET, database password) before deploying.
Use HTTPS in production (place a reverse proxy like Nginx or Traefik in front).
Store VyOS API keys securely – they are never logged or exposed.
Regularly backup the PostgreSQL volume (postgres_data).
Keep VyManager and VyOS updated.

❓ Troubleshooting

Cannot Connect to VyOS Instance

Verify the API key is correct and the REST/GraphQL services are enabled.
Ensure network connectivity between VyManager and the router.
If using self‑signed certificates, disable SSL verification or add your CA certificate (see Custom CA Certificates).

Containers Not Starting

Check logs:

docker compose logs postgres
docker compose logs backend
docker compose logs frontend

Database Connection Failed

Ensure the DATABASE_URL in .env uses postgres as the hostname (the Docker service name) and the credentials match.

VyOS API Timeouts with Large Configurations

Note

VyOS has known performance issues with large configurations, causing commits and boot times to take longer. See VyOS T5388.

When making changes (e.g., reordering NAT rules) and the commit via the API takes longer than the default timeout, the operation may appear to fail or the UI may refresh before the commit completes.

Solution:

Increase the API timeout in VyManager to a higher value (maximum 300 seconds). You can set this in the instance settings.
Verify that the commit actually applied

Monitoring and Console tabs do not work or connect

The monitoring and console pages open WebSocket connections to the same origin at /vyos/monitoring/ws/... and /vyos/console/ws/...; the proxy must upgrade those paths and forward them to the backend, or those two pages will not work.

Solution:

These pages need per-instance SSH set up first (Site Manager → edit instance → SSH); the page says so if the key is missing. Verify the public key is committed on the router and the SSH port is reachable.
Put a reverse proxy with TLS in front of VyManager: https://docs.vyprojects.org/operations/reverse-proxy/
The backend checks the WebSocket Origin header against TRUSTED_ORIGINS — the browser URL must be listed there.

SSH Key Generation Fails

If you see "Failed to generate SSH key" when setting up SSH for real-time monitoring, the SSH_ENCRYPTION_KEY is most likely missing from your .env file.

Cause:
VyManager uses this key to encrypt the generated SSH private key before storing it in the database. Without it, generation cannot complete.

Solution:

Generate a strong hex key:
```
openssl rand -hex 32
```

Add it to your .env:

SSH_ENCRYPTION_KEY=your-generated-hex-key

Restart the backend container:
```
docker compose restart backend
```
Try generating the SSH key again via the VyManager UI.

Important

Also verify that you have entered the correct SSH username and port. The SSH service on VyOS must be running and the user must have sufficient privileges.

Tip

Check the backend logs for errors:

docker compose logs backend | grep -i ssh

🤖 AI Integration with VyMCP

Want to let AI agents manage your VyOS routers?
Check out VyMCP – an MCP server that wraps the VyManager API, giving Claude, IDEs, and automation tools safe, audited access to your routers.

VyMCP inherits VyManager's per‑user authentication, RBAC, audit logging, and commit‑confirm safety – so every action is attributed, scoped, and reversible.

Read‑only by default – write tools are opt‑in via VYMANAGER_ENABLE_WRITES=true
Propose → apply flow – changes are reviewed before execution
Token‑scoped – restrict to specific sites or instances

🤝 Contributing

We welcome contributions! Please see our CONTRIBUTING.md for guidelines.

Fork the repository.
Create a feature branch (git checkout -b feat/amazing-feature).
Commit your changes (git commit -m 'feat: add amazing feature').
Push to the branch (git push origin feat/amazing-feature).
Open a Pull Request.

📄 License

See LICENSE.md for details.

💬 Support

Documentation: https://docs.vyprojects.org/
Issues: GitHub Issues
Discord: Join our community

Built with ❤️ for the VyOS community

Name		Name	Last commit message	Last commit date
.github		.github
backend		backend
certs		certs
container		container
docs-site		docs-site
frontend		frontend
.gitattributes		.gitattributes
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile.backend		Dockerfile.backend
Dockerfile.frontend		Dockerfile.frontend
LICENSE.txt		LICENSE.txt
README.md		README.md
VERSION		VERSION
gitattributes.txt		gitattributes.txt
install.sh		install.sh
package-lock.json		package-lock.json
package.json		package.json

Uh oh!

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

VyManager

📖 Table of Contents

🚀 About VyManager

✨ Features

🖼️ Screenshots

⚡ Quick Start

📋 Prerequisites

1. Docker & Docker Compose (for Docker setup)

2. Enable the VyOS REST API and GraphQL

📦 Installation

Automated Script (Linux)

Docker Setup

Prerequisites (already covered above)

1. Create the Project Directory

2. Create docker-compose.yml

3. Create the .env File

4. Start VyManager

⚙️ Configuration

Custom CA Certificates

🧭 Post‑Installation Setup Wizard

🛠️ Managing Your Deployment

Updating VyManager

Common Docker Commands

🗂️ Managing Multiple VyOS Instances

Adding More Sites

Adding Instances to a Site

Connecting to an Instance

Switching Between Instances

🧩 Version‑Aware Architecture

How It Works

🧰 Tech Stack

Frontend

Backend

Infrastructure

👨‍💻 Development / Manual Setup

Frontend Development

Backend Development

Database Migrations

🔒 Security Considerations

❓ Troubleshooting

Cannot Connect to VyOS Instance

Containers Not Starting

Database Connection Failed

VyOS API Timeouts with Large Configurations

Monitoring and Console tabs do not work or connect

SSH Key Generation Fails

🤖 AI Integration with VyMCP

🤝 Contributing

📄 License

💬 Support

About

Topics

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages

2. Create `docker-compose.yml`

3. Create the `.env` File