Meet `vrg`: The CLI That Makes VergeOS Agent-Native

David Vincent

David Vincent

— 6 min read
Share

If you run a VergeOS cluster, you’ve probably moved between three control surfaces:

  • The WebUI for clicking around
  • The REST API for scripting
  • The Terraform provider for declarative infrastructure

The Verge.io team has now shipped a fourth option: vrg.

But the important story is not simply “VergeOS has another CLI.” The important story is that VergeOS now has a control surface that an LLM agent can drive end-to-end.

vrg is a Python CLI built on top of the pyvergeos SDK. It is Apache 2.0 licensed, available as version 1.1.1, and designed around the kinds of operational patterns that both humans and AI agents need: deterministic exit codes, name-based lookups, structured JSON output, recipe introspection, dry-run support, and built-in diagnostics.

After spending time with it, the conclusion is straightforward: this may be one of the most important VergeOS automation releases yet.

Why This Matters for AI Agents

Until now, handing VergeOS automation to an LLM agent usually meant one of two things.

First, you could give the agent access to the raw REST API. That works, but every action becomes a multi-step exercise:

  • Find the integer key for a named object
  • Format the correct request body
  • Hope recipe defaults behave as expected
  • Parse endpoint-specific response shapes
  • Determine whether the requested action actually completed

Agents can do this, but it burns tokens, increases failure modes, and encourages confident wrong turns.

Second, you could build a custom MCP server or wrapper around the API. That also works, but now every VergeOS feature you want to expose becomes your responsibility to model, test, and maintain.

vrg collapses both approaches into a single consistent interface. An agent with shell access and a configured VergeOS profile can manage compute, networking, storage, identity, replication, recipes, automation, and diagnostics without needing a custom translation layer.

That is the difference between “an agent can technically use the platform” and “an agent can operate the platform autonomously.”

What vrg Includes

vrg exposes a broad VergeOS control surface, with more than 200 commands across 28 domains.

Coverage includes:

  • Compute
    VMs, drives, NICs, devices, snapshots, GPU passthrough, import, and export

  • Networking
    Networks, firewall rules, DNS, hosts, aliases, diagnostics, and dashboards

  • Tenants
    Nodes, storage, networks, snapshots, recipes, and statistics

  • NAS
    Services, CIFS shares, NFS exports, sync, users, volumes, and files

  • Identity and access
    Users, groups, permissions, API keys, OIDC, and external authentication sources

  • Sites and replication
    Incoming and outgoing sync with schedules

  • Automation
    Tasks, schedules, triggers, events, scripts, and webhooks

  • Recipes and catalog
    Full lifecycle management, including recipe question introspection

  • Operations
    Updates, certificates, tags, resource groups, alarms, history, logs, and doctor

That breadth matters. The moment a CLI has a major hole, an agent has to fall back to the REST API or ask a human. Either case breaks the autonomy loop.

The Agent-Friendly Design Choices

Several vrg features look like ordinary CLI polish at first glance. For autonomous agents, they are load-bearing.

Deterministic Exit Codes

vrg uses predictable exit codes:

0  success
2  usage error
4  authentication error
6  not found
7  conflict
9  timeout
10 connection error

That means an agent can branch on behavior without parsing English error strings.

There is a big difference between:

  • Retry this
  • Ask for new credentials
  • The object does not exist
  • The name is ambiguous
  • This command was malformed

A single integer makes that distinction scriptable.

Name-Based Lookups

Agents reason about names better than surrogate keys.

With vrg, you can use commands like:

vrg vm start engineering-server

instead of:

vrg vm start 115

The server resolves names and fails loudly when there is ambiguity. That makes workflows much easier for both humans and agents to compose.

JSON Output and Field Queries

vrg supports structured output:

vrg -o json vm list --query 'name,status,ram'

That gives an agent exactly the fields it needs in a parseable shape. No scraping tables. No brittle column parsing. No guessing where a value appears in formatted output.

Recipe Question Introspection

This may be the most important feature for agents:

vrg recipe question list "Debian 13 (Trixie)"

VergeOS recipes often have hidden or required answers. If an agent misses one, a deployment may technically “succeed” while producing a broken VM: no disk, no SSH key, no usable network configuration.

Recipe question introspection lets the agent discover the full answer schema before deploying. That turns recipe deployment from guessing into planning.

vrg doctor

When something is wrong, an agent needs a reliable diagnostic entry point.

vrg doctor

Instead of trying to infer state from scattered failures or logs, the agent can run one command and receive a structured diagnosis of configuration or cluster issues.

Dry Runs

For template-driven VM creation, --dry-run provides a safe preview:

vrg vm create -f web.vrg.yaml --set ENV=prod --dry-run

That gives both humans and agents a way to validate intended infrastructure before committing changes.

A Quick Tour

Installation options include:

uv tool install vrg

or:

pipx install vrg

or:

brew install verge-io/tap/vrg

Then configure access:

vrg configure setup

Run a basic sanity check:

vrg system info

List common resources:

vrg vm list
vrg recipe list
vrg network list

Use structured output when needed:

vrg -o json vm list --query 'name,status,ram'

Deploying a VM End-to-End

A realistic workflow might be:

  1. Create an isolated network for a team
  2. Deploy a Debian server onto that network
  3. Assign a static IP
  4. Start the VM once the imported disk is ready

Create the network:

vrg network create --name engineering --cidr 10.0.12.0/24 --dhcp \
  --dhcp-start 10.0.12.100 --dhcp-stop 10.0.12.200 \
  --vnet-default-gateway External

vrg network start engineering

Then add the firewall and routing rules appropriate for your environment. One important detail: setting --vnet-default-gateway does not necessarily create the route rule for outbound traffic. You still need a default gateway rule pointing at the upstream vnet that handles NAT in your cluster.

After applying rules and DNS, confirm the network is ready before deploying VMs onto it.

Deploy the VM:

vrg recipe deploy "Debian 13 (Trixie)" --name engineering-server \
  --set HOSTNAME=engineering-server \
  --set USER=adminuser \
  --set PASSWORD='<password>' \
  --set "SSH_KEY=$(cat ~/.ssh/id_ed25519.pub)" \
  --set YB_CPU_CORES=4 \
  --set YB_RAM=2048 \
  --set YB_DRIVE_OS_SIZE=26843545600 \
  --set SELECT_OS_TIER=1 \
  --set YB_NIC_ETH0=engineering \
  --set YB_IP_ADDR_TYPE=static \
  --set YB_NIC_ETH0_IP_ADDR=10.0.12.2 \
  --set YB_NIC_ETH0_CIDR=/24 \
  --set YB_NIC_ETH0_GW=10.0.12.1 \
  --set YB_NIC_ETH0_NS=8.8.8.8

For cloud-image recipes, disk import may continue after the recipe request returns. A simple retry loop handles that cleanly:

until vrg vm start engineering-server; do sleep 10; done

At that point, the VM should be reachable with the configured SSH key from the appropriate network path.

A few operational notes matter here:

  • Use recipe introspection first
    Run vrg recipe question list "Debian 13 (Trixie)" before deploying so you know which answers are required.

  • Static IPs require static mode
    Setting an IP address alone is not enough. Use YB_IP_ADDR_TYPE=static with the related IP, CIDR, gateway, and nameserver fields.

  • Check the NIC after deployment
    If the requested static IP is already reserved, the deploy may succeed while the VM NIC is left without the expected IP.

  • Names work where IDs used to be painful
    YB_NIC_ETH0=engineering is much nicer than looking up and passing a numeric network key.

.vrg.yaml Templates

For repeatable deployments, vrg supports declarative templates.

Example:

name: web-${ENV}
ram: 4GB
cpu: 4
recipe: "Debian 13 (Trixie)"
answers:
  USER: deploy
  YB_NIC_ETH0: kubernetes
  YB_IP_ADDR_TYPE: static
drives:
  - name: data
    size: 100GB
nics:
  - network: kubernetes

Preview it:

vrg vm create -f web.vrg.yaml --set ENV=prod --dry-run

Apply it:

vrg vm create -f web.vrg.yaml --set ENV=prod

The template pipeline handles variable substitution, JSON schema validation, unit parsing, name-to-key resolution, batch creation, and dry-run previews.

It is exactly the kind of glue many teams would eventually build themselves. Having it built into the official CLI is better.

Features That Are Easy to Underestimate

A few features stand out because they are not flashy, but they matter in real operations.

Multi-Profile Authentication

~/.vrg/config.toml supports named profiles. You can switch with:

vrg --profile prod ...

or:

VERGE_PROFILE=prod

Supported authentication methods include bearer token, API key, and basic auth, with clear precedence across CLI arguments, environment variables, profiles, defaults, and prompts.

Diagnostics

vrg doctor gives you a purpose-built diagnostic tool instead of forcing every operator or agent to rediscover the same troubleshooting path.

Recipe Answer Schemas

vrg recipe question list <recipe> prevents one of the most frustrating automation outcomes: “the deploy succeeded, but the VM is broken.”

Auto-Update for Recipe Instances

vrg recipe deploy --auto-update

This keeps a VM aligned when the underlying recipe is republished, which is useful for fleet-style management.

Shell Completion

Completion support is available for bash, zsh, fish, and PowerShell.

When You Might Still Need the WebUI

There is one notable gap: VM console output.

The console is consumed by the WebUI over a websocket and is not exposed through the REST API in a CLI-friendly way. For boot-time debugging, you may still need a browser.

Beyond that, the CLI surface is broad enough that there are few obvious reasons to fall back to lower-level tooling for day-to-day automation.

Why This Is Bigger Than a CLI

The REST API remains useful, but it is a generic interface. Every interaction begins with object lookup, request formatting, response parsing, and platform-specific convention handling.

vrg packages those conventions into a tool that understands VergeOS.

For a human, that is the difference between writing assembly and calling a library function.

For an LLM agent, it is the difference between being able to operate the platform autonomously and not.

A virtualization platform with an agent-drivable CLI can participate directly in modern AI-driven infrastructure workflows. You can hand an agent a task like:

Stand up an isolated dev environment for the new team with a Debian VM and a 100GB data disk.

With vrg, that task can become an actual sequence of safe, inspectable CLI operations instead of a pile of custom API calls or manual dashboard work.

The fact that the Verge.io team built this themselves says something important about where infrastructure automation is going.

Install it:

uv tool install vrg

Then point an agent at it.

Read more