NanoKVM Ruby Gem

A Ruby library and CLI for controlling NanoKVM devices.

Install the gem:

gem install nanokvm

Or add to your Gemfile:

gem 'nanokvm'

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

First, configure your default device settings:

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

nanokvm info

Press the power button (short press):

nanokvm power

Long press (force shutdown):

nanokvm power --duration 8000

Press the reset button:

nanokvm reset

nanokvm leds

Check if the device is using the default password:

nanokvm is-password-updated

List available images:

nanokvm images

Mount an image:

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

Show virtual device status:

nanokvm virtual

Toggle virtual network or disk:

nanokvm toggle network
nanokvm toggle disk

Send keyboard input to the target:

nanokvm type "ls -la"

Check Tailscale extension status:

nanokvm tailscale

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

Get information about the NanoKVM hardware:

nanokvm hardware

Get or set memory limits:

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

Get or set OLED sleep timeout:

nanokvm oled
nanokvm oled --sleep=60

Get SSH server status:

nanokvm ssh-status

Get mDNS status:

nanokvm mdns

Get Wake-on-LAN MAC address:

nanokvm wol-mac

Get CD-ROM information:

nanokvm cdrom

Get script information:

nanokvm script

Get or set HID mode:

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

Get or set preview state:

nanokvm preview
nanokvm preview --enable=true

require 'nanokvm'

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

# Authenticate
client.login

# 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")

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.login

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)

Bug reports and pull requests are welcome on GitHub.

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