NanoKVM Ruby Gem

A Ruby library and CLI for controlling NanoKVM devices.

Installation

Install the gem:

gem install nanokvm

Or add to your Gemfile:

gem 'nanokvm'

CLI Usage

The nanokvm command provides a convenient way to interact with your NanoKVM device.

Configuration

First, configure your default device settings:

nanokvm configure --host 192.168.1.18 --username admin --password admin

Getting Device Info

nanokvm info

Power Control

Press the power button (short press):

nanokvm power

Long press (force shutdown):

nanokvm power --duration 8000

Press the reset button:

nanokvm reset

LED Status

nanokvm leds

Password Status

Check if the device is using the default password:

nanokvm is-password-updated

Virtual Disks

List available images:

nanokvm images

Mount an image:

nanokvm mount /data/ubuntu-24.04-desktop-amd64.iso

Virtual Devices

Show virtual device status:

nanokvm virtual

Toggle virtual network or disk:

nanokvm toggle network
nanokvm toggle disk

Type Text

Send keyboard input to the target:

nanokvm type "ls -la"

Tailscale

Check Tailscale extension status:

nanokvm tailscale

Image Download

Check if downloading images is enabled:

nanokvm download-enabled

Check status of image download:

nanokvm download-status

Monitor download progress until completion (includes download speed and time estimate):

nanokvm download-status --monitor
nanokvm download-status --monitor --interval=5  # Update every 5 seconds
nanokvm download-status --monitor --timeout=60  # Stop monitoring after 60 seconds

Download an image from URL:

nanokvm download-image https://releases.ubuntu.com/24.04.2/ubuntu-24.04.2-live-server-amd64.iso

Hardware Information

Get information about the NanoKVM hardware:

nanokvm hardware

Memory Management

Get or set memory limits:

nanokvm memory-limit
nanokvm memory-limit --enabled=true --limit=512

OLED Settings

Get or set OLED sleep timeout:

nanokvm oled
nanokvm oled --sleep=60

SSH, mDNS and Wake-on-LAN

Get SSH server status:

nanokvm ssh-status

Get mDNS status:

nanokvm mdns

Get Wake-on-LAN MAC address:

nanokvm wol-mac

CD-ROM and Script

Get CD-ROM information:

nanokvm cdrom

Get script information:

nanokvm script

HID Mode and Preview

Get or set HID mode:

nanokvm hid-mode
nanokvm hid-mode --mode=usb

Get or set preview state:

nanokvm preview
nanokvm preview --enable=true

Ruby Library Usage

Basic Usage

require 'nanokvm'

# Create a client
client = NanoKVM::Client.new(
  host: "192.168.1.18",
  username: "admin",
  password: "admin"
)

# Authenticate
client.

# Get device info
info = client.get_device_info
puts info.inspect

# Press power button
client.power_button

# Mount ISO
client.mount_image("/data/ubuntu-24.04-desktop-amd64.iso")

# Send text
client.send_text("Hello from Ruby")

Configuration

You can set default configuration options:

NanoKVM.configure do |config|
  config.default_host = "192.168.1.18"
  config.default_username = "admin"
  config.default_password = "admin"
end

# Now you can create clients without specifying parameters
client = NanoKVM::Client.new
client.

Available Methods

The client provides these main methods:

  • login
  • get_device_info
  • get_gpio_state
  • power_button(duration = 800)
  • reset_button(duration = 200)
  • get_available_images
  • get_mounted_image
  • mount_image(file_path)
  • get_virtual_device_status
  • toggle_virtual_device(device) (device can be "network" or "disk")
  • send_text(content)
  • reset_hid
  • is_password_updated
  • get_account_info
  • get_network_info
  • get_app_version
  • system_reboot
  • reset_hdmi
  • get_tailscale_status
  • is_download_image_enabled
  • get_download_image_status
  • download_image(url)
  • get_hardware_info
  • get_script_info
  • get_memory_limit
  • set_memory_limit(enabled, limit_mb)
  • get_oled_info
  • set_oled_sleep(sleep_seconds)
  • get_ssh_status
  • get_mdns_status
  • get_cdrom_info
  • get_wol_mac
  • get_hid_mode
  • set_hid_mode(mode)
  • get_preview_state
  • set_preview_state(enable)

Contributing

Bug reports and pull requests are welcome on GitHub.

License

The gem is available as open source under the terms of the MIT License.