Self-Deployed Lightweight Cloud KVM Remote Management Platform

中文文档 | English

Self-Deployed Lightweight Cloud (GLKVM Cloud) lets individuals and small businesses manage GL.iNet KVMs remotely from a server of their own, so their data and bandwidth stay with them. It is based on rttys.

Main Features

• User and Device Groups - Assign device groups to user groups, so that different users manage different devices
• Access Code Onboarding - Add a KVM by pasting an access code into its local web UI; the device proves itself with its factory certificate
• KVM Terminal - A web terminal on the KVM's own system
• Remote Control - Control the KVM's remote desktop in the browser
• Batch Commands - Run a command on several devices at once
• LDAP and OIDC Sign-in - Sign in with your company directory or identity provider
• Deployment - On an internal network or the internet, on x86_64 or arm64

Self-Hosting Guide

The following operating systems have been tested:

Debian Family

• Ubuntu 22.04 / 24.04
• Debian 12

Red Hat Family

• AlmaLinux 8 / 9
• Rocky Linux 8 / 9
• CentOS Stream 9

Older systems such as Ubuntu 20.04 and Debian 11 ship a Docker Compose that cannot read the deployment files. On them, use the manual Docker install with Docker Compose 1.27 or later, or with the docker compose plugin.

Requirements

Component	Minimum Requirement
CPU	1 core or above
Memory	≥ 1 GB
Storage	≥ 40 GB
Network Bandwidth	≥ 3 Mbps
KVM Device Firmware	≥ v1.11.0

Cloud Security Group Settings

If your server provider uses a cloud security group (e.g. AWS, Alibaba Cloud), make sure the following ports are open:

Port	Protocol	Purpose
443	TCP	Web UI
10443	TCP	Remote access to devices (Remote Control)
5912	TCP	Devices added with the old script (deprecated, see Devices on Old Firmware); not needed on a new installation
5915	TCP	Devices added with an access code
3478	TCP/UDP	TURN server for WebRTC

No other application on the server may use these ports, or the platform may fail to start.

Installation

There are two ways to install GLKVM Cloud.

A) One-line installer (recommended, x86_64/amd64)

The installer sets up Docker and Docker Compose, downloads the images and starts the services. Run it as root:

( command -v curl >/dev/null 2>&1 && curl -fsSL https://kvm-cloud.gl-inet.com/selfhost/install.sh || wget -qO- https://kvm-cloud.gl-inet.com/selfhost/install.sh ) | sudo bash

If the system has no sudo, drop it from the end of the command.

The installer puts everything in glkvm_cloud under the current directory, for example /root/glkvm_cloud. This guide calls it ~/glkvm_cloud.

B) Docker manual install

For x86_64 (amd64) and arm64 (AArch64). See docker-compose/README.md.

Platform Access

When the installation completes, the installer prints the platform URL and the admin username and password, for example:

   🌐 You can now access the GLKVM Cloud platform at:
       https://<your_server_public_ip>

   👤 Admin username:
       admin

   🔑 Admin password:
       <auto-generated-password>

Opening the platform by IP address triggers a browser certificate warning. To remove it, use your own domain and certificate, see Use Your Own Domain and SSL Certificate.

If the page does not open, check that both services are running with cd ~/glkvm_cloud && docker-compose ps. If one keeps restarting, docker-compose logs rttys coturn shows why.

On an internal network, set GLKVM_ACCESS_IP in ~/glkvm_cloud/.env to the server's internal IP address and restart the services. Otherwise the platform uses its public IP, which devices on the internal network may not reach.

Upgrade

Upgrade the deployment files together with the image. Changing only the image tag is not enough: the docker-compose.yml of releases before v3.0 does not publish port 5915, so devices cannot join with access codes (the Add Device dialog warns about it).

Installed with the one-line installer:

1. Back up the database:

   cp -a ~/glkvm_cloud/database ~/glkvm_cloud-database-backup

2. Run the installer again as root, from the directory that holds glkvm_cloud, not from inside it. It downloads the new image and deployment files, keeps .env and the database, and restarts the services.

3. Allow 5915/TCP in the cloud security group.

Installed by hand: run these in the directory that holds your docker-compose.yml.

1. Back up database, as above.

2. Update the deployment files: git pull if you cloned this repository, or download and extract the package. Neither touches .env or the database:

   curl -fsSLO https://kvm-cloud.gl-inet.com/selfhost/docker-compose.tar.gz
   tar -xzf docker-compose.tar.gz

3. Check .env. Since v3.0 these settings have no defaults, and the platform or coturn does not start while one of them is empty: RTTYS_PASS, TURN_USER, TURN_PASS, and RTTYS_TOKEN while RTTYS_LEGACY_TOKEN_ACCESS is on. If they were empty before, devices on old firmware use the former defaults, so set these to keep them working until they move to access codes:

   RTTYS_TOKEN=DeviceTokenYouCanChangeMe
   TURN_USER=glkvmcloudwebrtcuser
   TURN_PASS=AnotherS3cret

4. Allow 5915/TCP in the cloud security group and firewall.

5. Get the new image and restart:

   docker-compose pull    # or: curl -fsSLO https://kvm-cloud.gl-inet.com/selfhost/glkvmcloud.tar && docker load -i glkvmcloud.tar
   docker-compose down && docker-compose up -d

   With the Docker CLI plugin, use docker compose instead of docker-compose.

The .env kept from an older release doesn't get the settings added in v3.0: DEVICE_ACCESS_HOST, RTTYS_DEVICE_MTLS_PORT, RTTYS_LEGACY_TOKEN_ACCESS and OIDC_PRIMARY_LOGIN. They take their defaults. To change one, add its line to .env.

Using GLKVM Cloud

Add KVM Devices

The device needs firmware v1.11.0 or later. If you will use your own domain, set it up first (see below), so that access codes point devices at the domain.

1. On the platform's Devices page, click Add Device, generate an access code and copy it. Each code works once, on any device, within 24 hours.

   

2. Open the device's local web UI (https://<device IP>), go to the Self-hosted Cloud page, paste the access code and save. A device already on another self-hosted platform has to disconnect from it on that page first.

3. The device joins and shows up in the device list:

   

The device checks the cloud with the CA in the access code, and the cloud checks the device by its factory certificate.

Devices on Old Firmware

Devices added with the old script keep connecting on port 5912 after the cloud is upgraded. New devices can only be added with access codes, which need firmware v1.11.0 or later; running the old script in a device's terminal is no longer supported. To move a device to access codes:

1. Upgrade the cloud first, then upgrade the device firmware to v1.11.0 or later.
2. Paste an access code on the device's Self-hosted Cloud page. The device keeps its record, ID and groups in the cloud; if it is still connected the old way, it switches over without going offline.

Port 5912 is deprecated and will be removed in a later release. Once no device uses it, set RTTYS_LEGACY_TOKEN_ACCESS=false in .env to close it, adding the line if it isn't there. A new installation with no such devices can set it from the start.

KVM Terminal

Remote Control

Use Your Own Domain and SSL Certificate (Optional)

If you just want to try GLKVM Cloud and don't mind the browser's certificate warning, skip this section and keep opening the platform by the server's public IP.

For production use, open the platform on your own domain with a valid certificate. Devices are then opened on subdomains such as https://<deviceId>.your-domain.com:10443, which needs a wildcard DNS record and a wildcard certificate. Behind Nginx you can open devices by path under the platform's domain instead, with a single-domain certificate: see Path-Based Device Access.

Add DNS Records

Hostname	Type	Value	Purpose
www	A	Your server's public IP	Platform web UI
*	A	Your server's public IP	Remote access to devices

Open the platform on a subdomain such as www, not on the bare domain: a device's address is the platform's with the first label replaced by the device ID, so www.your-domain.com gives <deviceId>.your-domain.com.

Use a Custom SSL Certificate

Get a wildcard certificate for *.your-domain.com, which covers both www.your-domain.com and the device subdomains. Let's Encrypt issues wildcard certificates with DNS validation only.

Put the certificate (full chain) and its private key, both in PEM format, in ~/glkvm_cloud/certificate under these names:

• glkvm.cer (Let's Encrypt's fullchain.pem)
• glkvm.key (Let's Encrypt's privkey.pem)

Without them, GLKVM Cloud generates a certificate on first start, which browsers do not trust. After renewing the certificate, copy the new files in and restart the services.

The ports devices connect to (5912 and 5915) don't use this certificate. They use one from the platform's own CA in ~/glkvm_cloud/database/pki. Keep that directory and back it up: devices that joined with an access code trust that CA and lose access if it is replaced.

Put the Domain in Access Codes (Optional)

Access codes point devices at GLKVM_ACCESS_IP by default. To have devices connect by the domain instead, so they keep working if the server's IP changes, set this in ~/glkvm_cloud/.env, adding the line if it isn't there:

DEVICE_ACCESS_HOST=www.your-domain.com

It applies to codes generated after the restart. Devices that already joined keep working.

Restart the Services

After changing the certificate or .env, restart GLKVM Cloud:

cd ~/glkvm_cloud
docker-compose down && docker-compose up -d

With the Docker CLI plugin, use docker compose instead of docker-compose. Then open the platform at https://www.your-domain.com.