ugos-cli

CLI, MCP server, and Rust client library for managing UGREEN NAS (UGOS) devices.

UGOS provides a web UI for KVM virtual machine management but no CLI or API documentation. Direct use of virsh/qemu on the host causes UGOS to lose track of VMs. This project provides a programmatic interface through the official (undocumented) API.

⚠️ Work in Progress — This project currently implements a subset of the UGOS API focused on KVM virtual machine management. See the implementation status below.

Crates

Quick Start

CLI

# Set credentials (or use --host, --user, --password flags)
export UGOS_HOST=192.168.2.5
export UGOS_USER=admin
export UGOS_PASSWORD=<password>

# List VMs
ugos-cli vm list

# Show VM details
ugos-cli vm show CachyOS

# Power management
ugos-cli vm start CachyOS
ugos-cli vm stop CachyOS
ugos-cli vm stop --force CachyOS

# Snapshots
ugos-cli vm snapshot list CachyOS
ugos-cli vm snapshot create CachyOS my-snapshot

# Other resources
ugos-cli network list
ugos-cli storage list
ugos-cli image list
ugos-cli info

# JSON output
ugos-cli -o json vm list

Library

use ugos_client::{UgosClient, Credentials};
use ugos_client::api::kvm::KvmApi;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let creds = Credentials {
        username: "admin".into(),
        password: "<password>".into(),
    };

    let client = UgosClient::connect("192.168.2.5", 9443, creds).await?;
    let vms = client.vm_list().await?;

    for vm in &vms {
        println!("{}: {}", vm.vir_display_name, vm.status);
    }

    Ok(())
}

MCP Server

Configure in your MCP client (e.g. Kiro, Claude Desktop):

{
  "mcpServers": {
    "ugos": {
      "command": "ugos-mcp",
      "env": {
        "UGOS_HOST": "192.168.2.5",
        "UGOS_USER": "admin",
        "UGOS_PASSWORD": "<password>"
      }
    }
  }
}

Multiple NAS targets are supported:

{
  "mcpServers": {
    "ugos": {
      "command": "ugos-mcp",
      "env": {
        "UGOS_HOST_1": "192.168.2.5",
        "UGOS_USER_1": "admin",
        "UGOS_PASSWORD_1": "<password>",
        "UGOS_NAME_1": "picard",
        "UGOS_HOST_2": "192.168.2.4",
        "UGOS_USER_2": "admin",
        "UGOS_PASSWORD_2": "<password>",
        "UGOS_NAME_2": "kirk"
      }
    }
  }
}

Installation

From GitHub Releases

Download pre-built binaries from the releases page.

Available for:

• Linux (x86_64, aarch64)
• macOS (x86_64, aarch64)
• Windows (x86_64, aarch64)

From Source

cargo install --git https://github.com/metaneutrons/ugos-cli ugos-cli
cargo install --git https://github.com/metaneutrons/ugos-cli ugos-mcp

Library

[dependencies]
ugos-client = "0.1"

Implementation Status

Implemented ✅

Not Yet Implemented

Authentication

UGOS uses a multi-step auth flow:

1. RSA key exchange — POST /verify/check returns an RSA public key
2. Password encryption — PKCS1v1.5 padding (not OAEP)
3. Login — POST /verify/login returns a session token + cookies
4. Authenticated requests — cookies + ?token= query parameter

The client handles this automatically, including transparent re-authentication when tokens expire (UGOS error code 1024).

Tested Devices

Requirements

• Rust 1.85+ (edition 2024)
• UGOS NAS with KVM app installed
• Network access to the NAS (HTTPS port 9443)

License

This project is licensed under the GNU General Public License v3.0.