gpu-cli

vz

Cross-platform runtime for containerized workloads and macOS VM automation.

vz provides one CLI for:

• OCI image and container lifecycle
• Multi-service stacks from Compose files
• macOS VM provisioning and control (Apple Virtualization.framework)

Typical use cases:

• Run isolated build/test workloads from OCI images
• Launch local multi-service environments from Compose
• Automate deterministic macOS VM test sandboxes

Why vz

• One interface, multiple runtimes. Use the same CLI flow on macOS and Linux.
• Container-native. Pull, run, create, exec, log, stop, and remove OCI workloads.
• Stack-aware. Bring up complete Compose apps with events, logs, and service exec.
• VM automation on macOS. Provision, run, exec, save, and restore macOS VMs over vsock.
• Script-friendly. Consistent command model with --json support across commands.

Install

curl -sSf https://raw.githubusercontent.com/gpu-cli/vz/main/scripts/install.sh | sh

This installs pre-built binaries (signed + notarized) and the Linux kernel to ~/.vz/bin/. Requires macOS on Apple Silicon.

Options:

• VZ_VERSION=0.3.0 — pin a specific version
• VZ_NO_LINUX=1 — skip Linux kernel download

Install from source

# Requires Rust 1.85+
cargo install --git https://github.com/gpu-cli/vz.git vz-cli
vz self-sign  # apply Virtualization.framework entitlements

Build the Linux kernel (for source installs)

cd linux && make docker-build  # requires Docker
mkdir -p ~/.vz/linux && cp linux/out/{vmlinux,initramfs.img,youki,version.json} ~/.vz/linux/

Platform support

• Linux: container + stack commands
• macOS (Apple Silicon): container + stack commands, plus vz vm ...

Quick start

1. Run commands in a Linux VM

cd your-project

# Generate a vz.json config (auto-detects Rust, Node, Python, Go)
vz init

# Run any command inside the Linux VM
vz run echo "hello from Linux"

# Compile and run a Rust project
vz run cargo build
vz run cargo test

# Open an interactive shell
vz run -i bash

# Check VM status
vz status

# Stop the VM when done
vz stop

The first vz run boots a Linux VM (~3s), pulls the base image, and runs setup commands from vz.json. Subsequent runs reuse the VM and skip setup (cached by hash).

vz.json

{
  "image": "ubuntu:24.04",
  "workspace": "/workspace",
  "mounts": [{ "source": ".", "target": "/workspace" }],
  "setup": [
    "apt-get update",
    "apt-get install -y build-essential curl"
  ],
  "env": { "PATH": "/root/.cargo/bin:/usr/local/bin:/usr/bin:/bin" },
  "resources": { "cpus": 4, "memory": "8G" }
}

2. Run a Compose stack

# Start services
vz stack up -f compose.yaml -n demo

# Inspect and stream logs
vz stack ps demo
vz stack logs demo --service web --follow

# Tear down
vz stack down demo --volumes

Stack networking defaults to service identity inside the stack network. Host-facing port publishing is explicit opt-in via Compose host bindings (HOST:CONTAINER); container-only ports remain internal.

3. Manage macOS VMs (macOS only)

# Create a pinned base image from the stable channel
vz vm init --base stable

# Provision account + guest agent after fingerprint verification (system mode is default)
sudo vz vm provision --image ~/.vz/images/base.img --base-id stable

# No-local-sudo local path (opt-in runtime policy)
vz vm provision --image ~/.vz/images/base.img --base-id stable --agent-mode user

# Verify a local image against the stable channel pin
vz vm base verify --image ~/.vz/images/base.img --base-id stable

# Start headless VM
vz vm run --image ~/.vz/images/base.img --name dev --headless &

# Execute in guest over vsock
vz vm exec dev -- sw_vers

# Save state and stop
vz vm save dev --stop

# Restore fast from saved state
vz vm run --image ~/.vz/images/base.img --name dev --restore ~/.vz/state/dev.vzsave --headless &

4. Pinned-base automation policy (macOS VM flows)

• vz vm init --base <selector>, vz vm provision --base-id <selector>, and vz vm base verify --base-id <selector> accept immutable base IDs plus channel aliases (stable, previous).
• Base descriptors include support lifecycle metadata (active or retired); selecting a retired or unknown base fails with explicit fallback guidance.
• Retirement guidance always includes vz vm init --base stable and, when available, a concrete replacement selector/base.
• vz vm patch verify and vz vm patch apply reject bundles targeting retired or unsupported base descriptors.
• Unpinned flows require explicit --allow-unpinned.
• In CI (CI=true), unpinned flows are blocked unless VZ_ALLOW_UNPINNED_IN_CI=1 is set.
• Runtime policy: --agent-mode system is the default for reliability; --agent-mode user is opt-in for no-local-sudo workflows.