Skip to main content

Glinet Kvm

@sntxrr/glinet-kvmv2026.10.19.1· MIT· 1mo agoBEHAVIORSACCEPTED WARNINGS
01README

Operate GL.iNet KVMs (Comet GL-RM1 / GL-RM1PE) from swamp: health, screenshots, ATX power and virtual media. The firmware is a fork of PiKVM's kvmd, and three of its behaviours shape this model. The factory TLS certificate is self-signed, names CN=localhost and expired in 1979, so it cannot be validated or pinned; HTTP goes through curl and the viewer through openssl, with credentials on stdin rather than argv. The video streamer sleeps until a viewer connects, so a bare snapshot request answers 503 whether or not there is a signal; screenshot and health open a receive-only viewer session first and never send input. Without the ATX add-on board, the API still reports power 'off' for a running machine; this model reports the state as unknown and refuses to press a button wired to nothing. health flags available firmware updates, missing HDMI signal, offline USB HID, forgotten virtual media that could hijack the next boot, clock skew, Tailscale (the device's own state, plus an optional probe of its tailnet IP that catches a node deleted from the tailnet, which the device still reports as Running), and security posture (2FA off, browser root shell on, untrusted TLS). Reads and writes are separate methods: atx and msd report state or record a plan and never change the device; atxPress and msdChange act, behind labeled live pre-flight checks (ATX board present and not busy; virtual media enabled and not busy).

02Behaviors1
@sntxrr/glinet-kvmv2026.10.19.1glinet_kvm.ts

Global Arguments

ArgumentTypeDescription
hoststringAddress of the KVM: a LAN IP or a hostname that resolves from wherever
port?numberHTTPS port of the KVM web UI.
username?stringWeb UI user. GL.iNet KVMs ship with a single `admin` account.
passwordstringWeb UI password. Supply a vault reference, never a literal. If two-
timeoutMs?numberPer-request timeout for API calls (uploads and downloads take their own).
tailnetIp?ipv4The KVM's Tailscale IPv4 address. When set, `health` checks that the
fn health(checkVideo?: boolean, checkFirmware?: boolean, strictSecurity?: boolean, maxClockSkewSeconds?: number)
Read-only health check: reachability, auth, firmware currency, HDMI signal, USB HID, attached virtual media, clock skew, ATX presence, Tailscale (state, and with tailnetIp an anonymous probe of the tailnet path that also checks the same device answers) and security posture (2FA, web terminal, TLS). Records an unreachable device as verdict 'fail' rather than throwing, so a scheduled check always leaves a record.
ArgumentTypeDescription
checkVideo?booleanWake the streamer with a receive-only viewer session to test for an HDMI signal. Sends no input.
checkFirmware?booleanAsk the device whether newer firmware exists (the device queries GL.iNet).
strictSecurity?booleanPromote security-posture findings (2FA off, web terminal on, untrusted TLS) from info to warn.
maxClockSkewSeconds?numberClock difference tolerated before a clock_skew warning.
fn screenshot(ocr?: boolean, waitMs?: number)
Capture a JPEG of the target's screen. Wakes the streamer with a receive-only viewer session (no input is sent), waits for a frame, and stores it as the `screenshot` file. Fails, after recording screenshotMeta, when there is no HDMI signal.
ArgumentTypeDescription
ocr?booleanAlso ask kvmd to OCR the frame and store the text in screenshotMeta.
waitMs?numberHow long to wait for the woken streamer to produce a frame.
fn atx(action?: enum, apply?: boolean)
Read-only: report ATX power state (action status), or plan a button action and record what it would do, including any refusal. Never presses anything; atxPress does. Since 2026.10.19.1 `apply: true` is refused here rather than ignored, so a caller written for the old method fails loudly instead of silently becoming a dry run.
ArgumentTypeDescription
action?enumon/off are soft (power button, only if state differs); off_hard holds power; reset_hard pulses reset; click_* press a button unconditionally.
apply?booleanRemoved in 2026.10.19.1: true is refused. Use atxPress.
fn atxPress(action: enum)
Drive the target's power/reset buttons. Always acts; plan first with `atx`. The labeled `live` pre-flight checks (ATX board present, not busy) run first; the method enforces the same conditions itself, since kvmd would accept a press with no board attached and nothing would happen.
ArgumentTypeDescription
actionenumon/off are soft (power button, only if state differs); off_hard holds power; reset_hard pulses reset; click_* press a button unconditionally.
fn msd(action?: enum, image?: string, file?: string, url?: string, cdrom?: boolean, transferTimeoutMs?: number, apply?: boolean)
Read-only virtual media (mass storage): status lists images and what is attached; any other action records the plan for msdChange with the same arguments, including any refusal. Never changes the device. Since 2026.10.19.1 `apply: true` is refused here rather than ignored.
ArgumentTypeDescription
action?enum
image?stringImage name on the KVM. Required for upload, download, connect, remove.
file?stringLocal path to upload (upload only).
url?stringURL the KVM downloads itself (download only). Better than upload for large ISOs over a slow link.
cdrom?booleanconnect: present as a CD-ROM (true) or a writable flash drive (false).
transferTimeoutMs?numberTimeout for upload and download.
apply?booleanRemoved in 2026.10.19.1: true is refused. Use msdChange.
fn msdChange(action: enum, image?: string, file?: string, url?: string, cdrom?: boolean, transferTimeoutMs?: number)
Change virtual media. Always acts; plan first with `msd`. upload streams a local ISO to the KVM; download has the KVM fetch a URL itself; connect attaches an image to the target as a CD-ROM or flash drive; disconnect detaches; remove deletes an image. The labeled `live` pre-flight checks (virtual media enabled, not busy) run first; the method enforces the same conditions itself, plus the ones that depend on the arguments.
ArgumentTypeDescription
actionenum
image?stringImage name on the KVM. Required for upload, download, connect, remove.
file?stringLocal path to upload (upload only).
url?stringURL the KVM downloads itself (download only). Better than upload for large ISOs over a slow link.
cdrom?booleanconnect: present as a CD-ROM (true) or a writable flash drive (false).
transferTimeoutMs?numberTimeout for upload and download.

Resources

health(infinite)— Device health, firmware currency and security posture.
atx(infinite)— ATX board state and the outcome of a power action.
msd(infinite)— Virtual media state and the outcome of an MSD action.
screenshotMeta(infinite)— Facts about the most recent screenshot.

Files

screenshot(image/jpeg)— JPEG frame of the target's screen.
03Previous Versions5
2026.10.18.2MIT
2026.10.18.1MIT
2026.10.14.1MIT(was none)

Declare SPDX license (MIT) in manifest.

2026.10.02.2

msd download: accept kvmd's streamed (newline-delimited) responses, so a completed download is reported as done. Verified live with the 1.7 GB Proxmox VE 9.2 ISO.

2026.10.02.1

First release. Verified live on two GL-RM1PE (firmware V1.9.1): health, screenshot, msd upload/connect/disconnect/remove (target saw the ISO). ATX presses and msd download are tested against a scripted kvmd only.

04Stats
A
100 / 100
Downloads
46
Archive size
39.8 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned

06Platforms
07Labels