# Install vm-cli for your AI agent

Official product: https://vm-cli.com
Publisher: Weerocks LLC
Version: 1.1.1
Release: 20261104-registered-nodes-1.1.1
Release date: 2026-11-04

This guide installs the local vm-cli executable and its Skill. Local virtual
machines do not require a Cloud account or a paid subscription. vm-cli supplies
virtual-machine controls; your existing agent client supplies the AI model.

## 1. Select the build for the host

Identify the operating system AND CPU architecture of the computer where vm-cli
will run. Choose exactly one matching artifact from the table below. Windows is
x64; macOS has separate Intel x64 (qualified on macOS 12.7.6) and Apple Silicon
ARM64 (qualified on macOS 26.5.1) builds; Linux has separate x64 and ARM64 builds.
These tested versions are not a claim that every other OS version is qualified.
Do not use Rosetta or a different architecture as
an assumed workaround. Check the full platform notes at
https://vm-cli.com/en/download/.

| Host build | Official download | Bytes | SHA-256 |
| --- | --- | ---: | --- |
| windows-x64 | [vm-cli.exe](https://vm-cli.com/downloads/1.1.1/windows-x64/registered-nodes-20261104/vm-cli.exe) | 59695608 | `fcc11c64c9470463cf1e45ed19ab7dc7918690d80120cf4b87c53f96d248d698` |
| macos-arm64 | [vm-cli](https://vm-cli.com/downloads/1.1.1/macos-arm64/registered-nodes-20261104/vm-cli) | 50110448 | `ceecfae22edc621db02332d14abbbdaa16ac8b74136d471fa9758ddf1669e347` |
| macos-x64 | [vm-cli](https://vm-cli.com/downloads/1.1.1/macos-x64/registered-nodes-20261104/vm-cli) | 45205488 | `9a83e9c2232cc9353f41dc76929082f92da7f0e0736f41daf85d9cabad085d4e` |
| linux-x64 | [vm-cli](https://vm-cli.com/downloads/1.1.1/linux-x64/registered-nodes-20261104/vm-cli) | 80039176 | `470727b50215e84b18f72c144dacc79af90133bbe6d1d542bfe6c0fb08741035` |
| linux-arm64 | [vm-cli](https://vm-cli.com/downloads/1.1.1/linux-arm64/registered-nodes-20261104/vm-cli) | 83329480 | `2ac7f8b09a5a38e34b4709eb43354fc8fc4a7e45c4bdf566c801b3eb31228307` |

Machine-readable metadata: https://vm-cli.com/agent-release.json
Use the platform-specific English manual and Skill linked below; each matches
the executable's own release and build ID.

### Windows networking release — 2026-11-04

The Windows x64 download is release `20261104-registered-nodes-1.1.1`, build
`104c91d12c9e8d48a2344b3410c41ce7659df18da174435b8dfcc29ac0065137`.

Windows supports independent NAT, shared NAT, internal networks, wired bridging,
per-card TCP/UDP NAT forwarding and multiple network cards. CLI, native GUI and
Web share the saved configuration. Network-card changes require a stopped VM;
only connecting or disconnecting an existing card is a live operation.

Use the matching [Windows manual](https://vm-cli.com/assets/windows-x64/CLI-HELP.md).
The [embedded Skill text](https://vm-cli.com/assets/windows-x64/SKILL.md) is available
for review; install it through the executable's setup command, which generates
the correct local paths and supporting references. Do not install this single
Markdown file by itself.

After replacing the executable, run `setup --action update --clients codex`
(or the actual selected client), then reload its Skill and verify installation.json.
For a first installation use `setup --clients codex`. This release's embedded
Skill describes stable NIC IDs/slots, exact revisions, explicit LAN exposure and
per-card Cloud mappings; do not use old single-card instructions.

Read `service status` before service-backed networking. For the first setup,
`service install` needs local Windows administrator approval. It installs a
protected copy of this same EXE as the system service and authorizes the initiating
Windows user. The original signed SeLow driver is embedded; no runtime driver
download or companion application is needed. Daily Agent, CLI, GUI and Web bridge
operations then use the service without repeated administrator prompts.

The client and service product version AND build ID must match exactly. After
replacing the EXE with another build, use that EXE's `service update` and let the
user approve Windows service maintenance. Do not elevate ordinary VM commands or
silently run an old client. Public service commands include status, install,
start, stop, restart, update and uninstall (delete is an alias); stopping or
replacing a service with active network use is refused.

Bridging does not move the host's IP, gateway or DNS. Initial driver binding may
briefly interrupt networking. The corrected Windows release also saves and disables
IPv4 LSO on the exact selected adapter while bridge grants use it. The first
preparation can briefly reconnect that adapter; the last removal restores its
recorded value. Multiple roots share this policy. IPv6 LSO and checksum offload
are unchanged. Stop affected bridge guests before applying/removing the policy;
never manually toggle global settings or replay an uncertain host request.
VPN-managed runtime host routes can change during a reconnect; vm-cli keeps
the observations and does not rewrite those routes or the configured gateway/DNS.
After a physical reconnect, the ordinary `network connect <vm> --nic <id> --revision <current>`
can recover the original SeLow member without restarting the VM.
Inspect `network capabilities` and the exact
preparation plan. Use a supported wired Ethernet adapter; do not promise Wi-Fi,
VPN or every USB adapter is compatible, and never disable system protection.
The browser cannot approve service installation or update; direct the user to
the local CLI for that system confirmation. It can prepare/remove bridges through
an already-authorized matching service. Do not silently replace a requested bridge
with NAT.


### Linux and macOS release — 2026-11-04

These four native downloads use release `20261104-registered-nodes-1.1.1`, build
`104c91d12c9e8d48a2344b3410c41ce7659df18da174435b8dfcc29ac0065137`. Independent NAT, shared NAT, internal networks, wired
bridging, multiple NICs and per-NIC TCP/UDP NAT forwarding are available through
CLI, native GUI and Web. Stop the VM before changing card topology or forwarding
rules. Stable NIC IDs and hardware slots survive edits; use the exact NIC ID for
multi-card operations. Guest routing is configured explicitly by the user.

- macOS · Apple Silicon ARM64: [manual](https://vm-cli.com/assets/macos-arm64/CLI-HELP.md) · [embedded Skill](https://vm-cli.com/assets/macos-arm64/SKILL.md)
- macOS · Intel x64: [manual](https://vm-cli.com/assets/macos-x64/CLI-HELP.md) · [embedded Skill](https://vm-cli.com/assets/macos-x64/SKILL.md)
- Linux · x64: [manual](https://vm-cli.com/assets/linux-x64/CLI-HELP.md) · [embedded Skill](https://vm-cli.com/assets/linux-x64/SKILL.md)
- Linux · ARM64: [manual](https://vm-cli.com/assets/linux-arm64/CLI-HELP.md) · [embedded Skill](https://vm-cli.com/assets/linux-arm64/SKILL.md)

Linux host bridge qualification covers Ubuntu 24.04.4 with NetworkManager 1.46
wired Ethernet and existing bridge/TAP paths. Local administrative preparation
uses a constrained role of the same executable; do not elevate ordinary VM tasks.
Do not assume support for an arbitrary network manager or a VPN-owned route.
Host firewall rules are not opened automatically.

Both Mac builds are Developer ID signed and Apple notarized. Wired vmnet bridge
preparation and revocation need normal local macOS administrator authorization.
The host IP, gateway and DNS remain in place. Wi-Fi bridging is not qualified.
Sleep/resume on Linux ARM64 and both Mac builds is explicitly deferred, not passed.

Update the managed Skill from the downloaded executable with
`setup --action update --clients codex` (or the actual selected client), then
`setup --action check --clients codex`. Reload the Skill and inspect its recorded
build ID. Do not install the review-only SKILL.md by itself: setup generates the
correct local paths and supporting references. Preserve edits when a conflict is
reported. Do not apply these new instructions to an older binary.


## 2. Download and verify BEFORE running

Use the exact HTTPS download URL above. Save to a stable, user-writable tools
directory, not a temporary folder. If vm-cli already exists, inspect its version
and managed Skill before replacing it. Preserve the existing executable, user
configuration and VM data when updating. Do not overwrite unrelated files.

Verify both file length and the SHA-256 in this guide. On Windows use
`Get-FileHash -Algorithm SHA256 -LiteralPath <downloaded-file>`; on macOS use
`shasum -a 256 <downloaded-file>`; on Linux use `sha256sum <downloaded-file>`.
Replace placeholders with real, correctly quoted paths. Stop if the digest
differs. Do not bypass operating-system signature, Gatekeeper or other security
prompts. Let the user handle a system approval if one is required.

On macOS/Linux, make the verified binary executable with `chmod +x <path>`.
This is a portable executable; no system-wide installer or sudo is normally
needed. Use its absolute path, or `./vm-cli` from its directory. In Windows
PowerShell use `.\vm-cli.exe` from its directory, or
`& 'C:\path\to\vm-cli.exe'` for an absolute path.

## 3. Check the executable and install the Skill

Run these commands using the verified executable:

```text
vm-cli version
vm-cli --help
vm-cli capabilities
vm-cli doctor
```

Here `vm-cli` stands for the actual executable path, not an assumption about
PATH. Read failures and platform limitations; don't report a successful install
if these checks failed. Help is a complete English Markdown manual; business
commands return structured JSON.

Select the agent client actually being used: `codex`, `claude-code`, or
`opencode`. Then run, for example:

```text
vm-cli setup --clients codex
vm-cli setup --action check --clients codex
```

For Claude Code use `--clients claude-code`; for OpenCode use
`--clients opencode`. Install only for the requested client(s), not all clients
by default. Specify `--clients` in noninteractive use. If the client is unknown,
ask which one to configure. Read `vm-cli setup --help` for project scope or an
existing modified Skill. Preserve user edits if setup reports a conflict.

Load the installed Skill according to the agent client's normal mechanism, read
its installation metadata, and use the recorded absolute executable path. If the
client needs to reload the session to discover it, tell the user. Skill installation
alone does not prove the model has loaded it or completed a VM task.

## 4. Hand back a useful result

Report the executable path, version, platform, verified checksum, configured
client and Skill check result. Do not automatically create a VM, open a GUI,
sign in to Cloud, purchase storage or change host security settings merely to
finish installation.

Once the user asks for VM work, follow the Skill: inspect host capabilities,
choose a compatible guest, observe its screen, send input and verify the result.
`create` prepares a machine; it does not install the operating system.
An agent can perform installation using suitable media and the VM controls.

For a prepared system, inspect `vm-cli cloud catalog` and `vm-cli run --help`,
choose an official version compatible with the host, and complete the normal
user-approved Cloud login if required. Use the command spelling in the selected
release's verified manual; this table is generated from those exact release documents:

| Host build | Upload | Download a verified cache | Create and start a local VM |
| --- | --- | --- | --- |
| windows-x64 | `vm-cli cloud push` | `vm-cli cloud pull` | `vm-cli run` |
| macos-arm64 | `vm-cli cloud push` | `vm-cli cloud pull` | `vm-cli run` |
| macos-x64 | `vm-cli cloud push` | `vm-cli cloud pull` | `vm-cli run` |
| linux-x64 | `vm-cli cloud push` | `vm-cli cloud pull` | `vm-cli run` |
| linux-arm64 | `vm-cli cloud push` | `vm-cli cloud pull` | `vm-cli run` |

New builds group transfers under `cloud push` and `cloud pull`; older builds may
still use the former top-level spelling shown above. After upgrading, refresh
the Skill with that new executable. `run` stays at the top level; `--on` selects its execution computer.
`cloud run` is not implemented. Private transfers use the signed-in account's
repositories. Do not assume an x86 guest is hardware-accelerated
on an ARM host. Local VM use is independent of paid cloud storage.

More examples: https://vm-cli.com/en/docs/quickstart/

## Unified management and portable images

Available in: Windows · x64, macOS · Apple Silicon ARM64, macOS · Intel x64, Linux · x64, Linux · ARM64.

Use `vm-cli ls` (`list` is an alias) to list VMs across registered local data
directories and computers, and `vm-cli ps` for VMs confirmed to be running. Keep the returned
`ref` for later commands. Check `complete`, per-source errors and observation
times; an unavailable directory is not an empty directory or a stopped VM.

Create an independent local VM from an exported image directory:

```text
vm-cli run --image ./images/dev --on local --name dev-copy
vm-cli image export VM_REF --output ./images/dev-backup --plan
vm-cli image export VM_REF --output ./images/dev-backup --request-id export-dev-001
vm-cli request show REQUEST_REF
```

Replace VM_REF and REQUEST_REF with the exact values returned by the executable.
The source must be stopped for export. External media needs an explicit include
or eject decision; credentials and host-device grants are not exported. Keep the
original request after interruption. A new request with an existing VM name is
rejected; use `start VM_REF` to start that VM. The same completed run request
returns its receipt without starting a stopped VM again.

`--image` selects the source, including a local directory, `cloud://` or
`official://`; it does not select where the VM runs. `--on local` means this
computer. Use `--on NODE` to run on a registered computer. Rented-cloud compute is not provided. In native managers use Media → Run image, Export VM image, or Image
tasks. The Web manager uploads a selected image folder and downloads exports as
ZIP64; extract an export to get the same local image directory format.


## Use your other computers

On each computer, sign in normally, inspect `root list`, then register only
the directories and roles you want to expose:

```text
vm-cli login
vm-cli root list
vm-cli node register --name office --grant ROOT_ID:manager --request-id enroll-office-001
vm-cli node serve
```

Keep `node serve` running as that computer's ordinary user. Registration does
not open a public Web listener or install a system service. On another client
signed into the same account, use the normal top-level VM commands:

```text
vm-cli ls
vm-cli ps
vm-cli show NODE_ID/VM_ID
vm-cli start NODE_ID/VM_ID --request-id start-dev-001
vm-cli view NODE_ID/VM_ID --viewer sdl
vm-cli run --image cloud://dev-images:v3 --on office --name dev-copy --request-id run-office-001
vm-cli cloud pull cloud://dev-images:v3 --on office --root-id ROOT_ID --request-id cache-office-001
vm-cli cloud push NODE_ID/VM_ID dev-images --version v4 --plan
```

Replace IDs with the exact returned values. `--image` selects the source;
`--on` selects where it runs. CLI, native manager and Web retain the same full
VM reference. Viewer opening is view-only; takeover and Send keys are explicit.
Closing a Viewer leaves the VM running. `cloud pull` fills a cache and does not
start a VM. Upload requires a stopped VM and a reviewed media selection.

Cloud handles account discovery and ICE signaling. VM commands, images and
frames use a direct WebRTC DataChannel; no custom relay is used. NAT, VPN or UDP
restrictions can prevent a direct connection even when STUN succeeds. Report the
actual error, preserve the original request reference and never silently retry a
VM creation or input on another computer.

