VPSGUI is a modern, production-ready, open-source Open Infrastructure Workspace for managing servers, containers, cloud resources, automation, and operations from a single unified workspace interface.
Developed by NotGamerPratham.
Repository: https://github.com/NotGamerPratham/vpsgui
VPSGUI's vpsgui-agent daemon executes shell commands, installs packages, controls systemd units
and Docker containers, and reads and writes files on the host. The agent token is equivalent to a
root password. Anyone who can reach the agent with that token owns the machine.
- Serve VPSGUI over HTTPS. The token is sent as a bearer header; over plain HTTP anything on the network path can capture it.
- Keep the agent on loopback (the default) behind the bundled nginx reverse proxy. Do not expose port 46509 to the internet.
- Put the UI behind a VPN, firewall, or authenticating proxy. The sign-in page is a local profile gate, not authentication - VPSGUI ships no user database, roles, or permissions.
See docs/SECURITY.md for the full model and the hardening knobs.
The sign-in screen is now real authentication, not a local profile gate.
- Accounts live in
/opt/vpsgui/agent/users.db- a0600JSON file. Passwords are hashed with scrypt (N=16384, r=8, per-user random salt) and compared in constant time. Nothing stores a password in plaintext, and the file is on the agent's credential deny-list, so the file manager refuses it even withAGENT_FILE_ROOTS=/. - The browser gets an HttpOnly, SameSite=Strict session cookie it cannot read, so an injected script cannot steal the session and a cross-site request never carries it. Sessions last 12 hours, are held in memory only (a restart signs everyone out), and are stored as a SHA-256 digest rather than the token.
- Failed sign-ins share the agent's lockout: 10 attempts locks that client out for 5 minutes. Unknown usernames are verified against a decoy hash so the response time cannot be used to enumerate accounts.
- Creating the first account requires the agent token, and is only possible while no account exists. There is no open registration endpoint.
Create it from the browser on first visit, or directly:
curl -X POST http://127.0.0.1:46509/api/v1/auth/bootstrap -H "Authorization: Bearer $(sudo grep -oP 'AGENT_TOKEN=\K.*' /opt/vpsgui/agent/agent.env)" -H 'Content-Type: application/json' -d '{"username":"admin","password":"choose-something-long"}'The agent token keeps working alongside this for the SDKs and scripts, and it remains root-equivalent - dashboard accounts do not replace it or reduce it.
Requires Node.js 18+. Clone, then run the deploy script as root - it installs dependencies,
builds the frontend, publishes it to /var/www/vpsgui/dist, installs the agent as a systemd
service, and configures nginx:
git clone https://github.com/NotGamerPratham/vpsgui.git && cd vpsgui && sudo ./run.shTo install only the agent on an additional Linux host, download and read the script before running
it as root - piping a remote script straight into sudo bash executes whatever the URL returns at
that moment, with no chance to inspect it:
curl -fsSLO https://raw.githubusercontent.com/NotGamerPratham/vpsgui/main/agent/install.shless install.sh && sudo bash install.shThe installer prints an agent token on completion. Paste it into the web UI under
Settings → Agent Token; without it every privileged endpoint returns 401.
- Nodes & Infrastructure Matrix: Manage Linux VPS hosts, Docker servers, and Kubernetes clusters in grid, table, or dynamic 4-way comparison matrix views.
- Interactive Topology Map: Visual node graph rendering path connections (Internet -> Load Balancers -> Compute Nodes -> Docker Engines & PostgreSQL Clusters).
- Spotlight Command Palette (
Ctrl+K): VS Code inspired spotlight search modal for nodes, containers, system logs, and quick actions. - SSH Workbench Split Terminal: Multi-tab terminal workbench with interactive command execution and saved snippet bar.
- VS Code File Explorer: Browse node filesystem trees (
/etc,/opt/stacks), edit config files, and inspect permissions. - Open Infrastructure Catalog: 1-Click deployment for applications, Docker container images, OS templates, and community plugins.
- Infrastructure as Code (IaC) Exporter: Declarative configuration exporter for Terraform HCL, Ansible Playbooks, Docker Compose, Helm Charts, and Cloud-Init.
- Real Network Diagnostics: Real DNS-over-HTTPS (DoH) resolution via Cloudflare (
1.1.1.1), HTTP fetch ping timing, and port inspection. - Secrets & HashiCorp Vault Store: Encrypted environment variables, secret API tokens, and deployment SSH keys.
- Multi-Theme Engine: Pre-loaded VS Code themes including VS Code Dark, Dracula, Catppuccin, Nord, Atom One Dark, and Tokyo Night.
VPSGUI/
├── apps/
│ ├── web/ # React 18 + Vite + TypeScript Web Workspace
│ └── docs/ # Technical Documentation Portal
├── packages/
│ ├── ui/ # Reusable Atomic UI Component Library
│ ├── sdk/ # VPSGUI TypeScript SDK & REST Client
│ ├── types/ # Domain TypeScript Interfaces
│ └── config/ # Shared ESLint, Tailwind & TS Configuration
├── sdk/
│ ├── node/ # vpsgui - Official CLI + Node.js/TypeScript SDK (npm)
│ └── python/ # vpsgui - Official Python SDK (PyPI)
├── backend/
│ ├── api/ # REST API Gateway & Authentication
│ ├── gateway/ # Reverse Proxy & SSL Management
│ └── telemetry/ # High-Throughput Telemetry Ingestion Engine
├── agent/
│ ├── vpsgui-agent.go # Lightweight Go/Rust Linux VPS Daemon
│ ├── install.sh # Automated Linux Installer Script
│ └── systemd/ # Systemd Unit File
├── docs/ # Developer Documentation Suite
├── deploy/ # Production Nginx Manifests
├── run.sh # All-in-one Linux Setup Script
└── docker-compose.yml # Production Docker Container Setup
-
Clone the repository:
git clone https://github.com/NotGamerPratham/vpsgui.git cd vpsgui -
Run All-In-One Setup Script:
chmod +x run.sh && ./run.sh
Everything here runs on Node.js 18+ or on Bun 1.2+. Node is the default
and what run.sh installs on a server; Bun is supported for local development
and is roughly three times faster to build.
bun install && bun run test && bun --bun run buildbun run <script> executes the package scripts, but note two details:
bun rundoes not shimnode. A script that namesnodeexplicitly — such asagent:start- still launches Node. Usebun run agent:start:bunon a machine that has only Bun.--bunis what makes Bun run the tooling. Vite's binary carries a#!/usr/bin/env nodeshebang, which Bun honours by default, so a plainbun run buildquietly builds on Node.bun --bun run buildruns Vite itself on Bun.
The build output is byte-for-byte identical either way, and CI runs the whole suite plus the agent under both runtimes.
The one place they genuinely differed: fs.realpath on a Windows drive root
returns F:\ on Node and F: on Bun. The agent normalises that before its
path-confinement check - without it, running the agent on Bun refused to list
its own configured root.
Both SDK packages install a vpsgui command. They are the same CLI and share
~/.vpsgui/config.json, so it does not matter which one wins on your PATH.
npm i -g vpsgui
# or
pip install vpsgui
vpsgui login vps.example.comlogin reads the agent token with echo off, verifies it against the agent, and only then writes it
to disk with mode 0600 - nothing is saved if the credentials do not work.
vpsgui status # CPU, memory, disk, failing checks
vpsgui health # exits non-zero on a red check
vpsgui ps # docker containers
vpsgui ls /etc # list a directory on the host
vpsgui exec 'systemctl status nginx'Several hosts are several profiles; --profile works on every command. In CI, set
VPSGUI_API_URL and VPSGUI_AGENT_TOKEN instead of logging in - they take precedence over any
saved profile, so nothing touches the disk.
VPSGUI provides official SDK client libraries for programmatic API access.
npm install vpsguiimport { VpsguiClient } from 'vpsgui';
const client = new VpsguiClient({
baseUrl: 'https://your-vps-ip/api/v1',
token: process.env.VPSGUI_AGENT_TOKEN,
});
const nodes = await client.nodes.list();
const containers = await client.docker.listContainers();
const telemetry = await client.system.telemetry();pip install vpsguiimport os
from vpsgui import VpsguiClient
client = VpsguiClient(
base_url="https://your-vps-ip/api/v1",
token=os.environ["VPSGUI_AGENT_TOKEN"],
)
nodes = client.nodes.list()
containers = client.docker.list_containers()
telemetry = client.system.telemetry()VPSGUI is 100% free and open-source software created and maintained by NotGamerPratham. If VPSGUI saves you time or powers your server infrastructure, consider sponsoring its ongoing development!
Want to contribute to VPSGUI? Check out our CONTRIBUTING.md guide!
Developed by NotGamerPratham.
VPSGUI is open-source software released under the MIT License.