vpsgui

Official CLI and Python SDK for the VPSGUI agent REST API.

Install

pip install vpsgui

Requires Python 3.8+. This installs both the vpsgui command and the library.

The CLI

vpsgui login vps.example.com

login asks for the agent token with echo off, checks it against the agent, and only then writes ~/.vpsgui/config.json with mode 0600. Nothing is saved if the credentials do not work.

Several hosts are several profiles; --profile works on every command.

vpsgui login vps-2.example.com --profile staging
vpsgui exec --profile staging 'systemctl restart nginx'

In CI, set VPSGUI_API_URL and VPSGUI_AGENT_TOKEN instead of logging in - they take precedence over any saved profile, so nothing touches the disk.

The npm package vpsgui installs a CLI by the same name that reads the same config file, so it does not matter which one wins on your PATH.

The agent token is a root password

Every endpoint except health() requires the agent token, and that token grants root-equivalent control of the host: shell execution, package installs, and filesystem read/write. Read it from the environment, never commit it, and only talk to the agent over HTTPS - it travels in the Authorization header.

The library

import os
from vpsgui import VpsguiClient

with VpsguiClient(
    base_url="https://vps.example.com/api/v1",
    token=os.environ["VPSGUI_AGENT_TOKEN"],
) as client:
    telemetry = client.system.telemetry()
    print(f"CPU {telemetry['cpuPercent']}% across {telemetry['cpuCores']} cores")

    for container in client.docker.list_containers():
        print(container["name"], container["state"], container["image"])

API

Errors

from vpsgui import VpsguiClient, VpsguiError

try:
    client.system.telemetry()
except VpsguiError as e:
    # status is 0 for transport failures (timeout, DNS, connection refused).
    print(e.status, e.endpoint, e.message)
    if e.is_auth_error:
        print("Bad token, or locked out after repeated failures.")

None values are deliberate

Fields the agent cannot determine are None rather than guessed. Check before formatting:

• smartHealth - needs smartctl and raw device access
• cpuPercent on a process - Windows tasklist reports none
• city / region from ip_info() - only when the provider reports nothing (e.g. a bogon address)
• size / tables / keys on a database - would need per-engine credentials
• downloadsCount / rating on a catalog item - the agent queries no registry

read() also returns truncated: True and editable: False for a file that exceeded the read cap. Do not write that content back - it would truncate the file on disk.

License

MIT © NotGamerPratham