{"id":47737754,"url":"https://github.com/gpu-cli/vz","last_synced_at":"2026-04-02T23:01:13.306Z","repository":{"id":348139191,"uuid":"1160542591","full_name":"gpu-cli/vz","owner":"gpu-cli","description":"Native macOS VM sandbox for Apple Silicon. Create, snapshot, and exec into macOS VMs in seconds. No SSH, no setup — just vsock.","archived":false,"fork":false,"pushed_at":"2026-03-30T23:27:57.000Z","size":7280,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-31T01:36:04.984Z","etag":null,"topics":["apple-silicon","cli","developer-tools","macos","mit-license","rust","sandbox","virtualization","virtualization-framework","vm"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gpu-cli.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security-assessment-gate.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-18T04:18:59.000Z","updated_at":"2026-03-30T23:28:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gpu-cli/vz","commit_stats":null,"previous_names":["gpu-cli/vz"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/gpu-cli/vz","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gpu-cli%2Fvz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gpu-cli%2Fvz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gpu-cli%2Fvz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gpu-cli%2Fvz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gpu-cli","download_url":"https://codeload.github.com/gpu-cli/vz/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gpu-cli%2Fvz/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31318132,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T21:35:00.834Z","status":"ssl_error","status_checked_at":"2026-04-02T21:34:59.806Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apple-silicon","cli","developer-tools","macos","mit-license","rust","sandbox","virtualization","virtualization-framework","vm"],"created_at":"2026-04-02T23:01:12.169Z","updated_at":"2026-04-02T23:01:13.292Z","avatar_url":"https://github.com/gpu-cli.png","language":"Rust","readme":"# vz\n\nCross-platform runtime for containerized workloads and macOS VM automation.\n\n`vz` provides one CLI for:\n- OCI image and container lifecycle\n- Multi-service stacks from Compose files\n- macOS VM provisioning and control (Apple Virtualization.framework)\n\nTypical use cases:\n- Run isolated build/test workloads from OCI images\n- Launch local multi-service environments from Compose\n- Automate deterministic macOS VM test sandboxes\n\n## Why vz\n\n- **One interface, multiple runtimes.** Use the same CLI flow on macOS and Linux.\n- **Container-native.** Pull, run, create, exec, log, stop, and remove OCI workloads.\n- **Stack-aware.** Bring up complete Compose apps with events, logs, and service exec.\n- **VM automation on macOS.** Provision, run, exec, save, and restore macOS VMs over vsock.\n- **Script-friendly.** Consistent command model with `--json` support across commands.\n\n## Install\n\n```bash\ncurl -sSf https://raw.githubusercontent.com/gpu-cli/vz/main/scripts/install.sh | sh\n```\n\nThis installs pre-built binaries (signed + notarized) and the Linux kernel to `~/.vz/bin/`.\nRequires macOS on Apple Silicon.\n\nOptions:\n- `VZ_VERSION=0.3.0` — pin a specific version\n- `VZ_NO_LINUX=1` — skip Linux kernel download\n\n### Install from source\n\n```bash\n# Requires Rust 1.85+\ncargo install --git https://github.com/gpu-cli/vz.git vz-cli\nvz self-sign  # apply Virtualization.framework entitlements\n```\n\n### Build the Linux kernel (for source installs)\n\n```bash\ncd linux \u0026\u0026 make docker-build  # requires Docker\nmkdir -p ~/.vz/linux \u0026\u0026 cp linux/out/{vmlinux,initramfs.img,youki,version.json} ~/.vz/linux/\n```\n\n## Platform support\n\n- **Linux:** container + stack commands\n- **macOS (Apple Silicon):** container + stack commands, plus `vz vm ...`\n\n## Quick start\n\n### 1. Run commands in a Linux VM\n\n```bash\ncd your-project\n\n# Generate a vz.json config (auto-detects Rust, Node, Python, Go)\nvz init\n\n# Run any command inside the Linux VM\nvz run echo \"hello from Linux\"\n\n# Compile and run a Rust project\nvz run cargo build\nvz run cargo test\n\n# Open an interactive shell\nvz run -i bash\n\n# Check VM status\nvz status\n\n# Stop the VM when done\nvz stop\n```\n\nThe 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).\n\n#### vz.json\n\n```json\n{\n  \"image\": \"ubuntu:24.04\",\n  \"workspace\": \"/workspace\",\n  \"mounts\": [{ \"source\": \".\", \"target\": \"/workspace\" }],\n  \"setup\": [\n    \"apt-get update\",\n    \"apt-get install -y build-essential curl\"\n  ],\n  \"env\": { \"PATH\": \"/root/.cargo/bin:/usr/local/bin:/usr/bin:/bin\" },\n  \"resources\": { \"cpus\": 4, \"memory\": \"8G\" }\n}\n```\n\n### 2. Run a Compose stack\n\n```bash\n# Start services\nvz stack up -f compose.yaml -n demo\n\n# Inspect and stream logs\nvz stack ps demo\nvz stack logs demo --service web --follow\n\n# Tear down\nvz stack down demo --volumes\n```\n\nStack networking defaults to service identity inside the stack network.\nHost-facing port publishing is explicit opt-in via Compose host bindings\n(`HOST:CONTAINER`); container-only ports remain internal.\n\n### 3. Manage macOS VMs (macOS only)\n\n```bash\n# Create a pinned base image from the stable channel\nvz vm init --base stable\n\n# Provision account + guest agent after fingerprint verification (system mode is default)\nsudo vz vm provision --image ~/.vz/images/base.img --base-id stable\n\n# No-local-sudo local path (opt-in runtime policy)\nvz vm provision --image ~/.vz/images/base.img --base-id stable --agent-mode user\n\n# Verify a local image against the stable channel pin\nvz vm base verify --image ~/.vz/images/base.img --base-id stable\n\n# Start headless VM\nvz vm run --image ~/.vz/images/base.img --name dev --headless \u0026\n\n# Execute in guest over vsock\nvz vm exec dev -- sw_vers\n\n# Save state and stop\nvz vm save dev --stop\n\n# Restore fast from saved state\nvz vm run --image ~/.vz/images/base.img --name dev --restore ~/.vz/state/dev.vzsave --headless \u0026\n```\n\n### 4. Pinned-base automation policy (macOS VM flows)\n\n- `vz vm init --base \u003cselector\u003e`, `vz vm provision --base-id \u003cselector\u003e`, and `vz vm base verify --base-id \u003cselector\u003e` accept immutable base IDs plus channel aliases (`stable`, `previous`).\n- Base descriptors include support lifecycle metadata (`active` or `retired`); selecting a retired or unknown base fails with explicit fallback guidance.\n- Retirement guidance always includes `vz vm init --base stable` and, when available, a concrete replacement selector/base.\n- `vz vm patch verify` and `vz vm patch apply` reject bundles targeting retired or unsupported base descriptors.\n- Unpinned flows require explicit `--allow-unpinned`.\n- In CI (`CI=true`), unpinned flows are blocked unless `VZ_ALLOW_UNPINNED_IN_CI=1` is set.\n- Runtime policy: `--agent-mode system` is the default for reliability; `--agent-mode user` is opt-in for no-local-sudo workflows.\n\n```bash\n# Explicit unpinned local flow\nvz vm init --allow-unpinned --ipsw ~/Downloads/restore.ipsw\nsudo vz vm provision --image ~/.vz/images/base.img --allow-unpinned\n```\n\n### 5. Create signed patch bundles\n\n```bash\n# Generate an Ed25519 signing key (PKCS#8 PEM)\nopenssl genpkey -algorithm Ed25519 -out /tmp/vz-patch-signing-key.pem\n\n# One-command inline patch creation (no operations.json or payload directory required)\nvz vm patch create \\\n  --bundle /tmp/patch-1.vzpatch \\\n  --base-id stable \\\n  --mkdir /usr/local/libexec:755 \\\n  --write-file /path/to/vz-agent:/usr/local/libexec/vz-agent:755 \\\n  --symlink /usr/local/bin/vz-agent:/usr/local/libexec/vz-agent \\\n  --set-owner /usr/local/libexec/vz-agent:0:0 \\\n  --set-mode /usr/local/libexec/vz-agent:755 \\\n  --signing-key /tmp/vz-patch-signing-key.pem\n\nvz vm patch verify --bundle /tmp/patch-1.vzpatch\nsudo vz vm patch apply --bundle /tmp/patch-1.vzpatch --image ~/.vz/images/base.img\n```\n\nFor advanced CI workflows, `vz vm patch create` also supports `--operations \u003cjson\u003e` + `--payload-dir \u003cdir\u003e`.\n\n### 6. Primary image-delta patch flow (sudo once, then sudoless apply)\n\n```bash\n# 1) Create a binary image delta from a signed bundle (runs bundle apply on a temp image copy)\nsudo vz vm patch create-delta \\\n  --bundle /tmp/patch-1.vzpatch \\\n  --base-image ~/.vz/images/base.img \\\n  --delta /tmp/patch-1.vzdelta\n\n# 2) Apply the binary delta without sudo to produce a new bootable image\nvz vm patch apply-delta \\\n  --base-image ~/.vz/images/base.img \\\n  --delta /tmp/patch-1.vzdelta \\\n  --output-image ~/.vz/images/base-patched.img\n\n# 3) Boot-test the patched image\nvz vm run --image ~/.vz/images/base-patched.img --name delta-test --headless\n```\n\n## Command groups\n\n### Dev environments\n\n`init`, `run`, `run -i`, `stop`, `status`, `logs`\n\n### Containers\n\n`pull`, `run`, `create`, `exec`, `images`, `prune`, `ps`, `stop`, `rm`, `logs`\n\n### Stacks\n\n`stack up`, `stack down`, `stack ps`, `stack ls`, `stack config`, `stack events`, `stack logs`, `stack exec`, `stack run`, `stack stop`, `stack start`, `stack restart`, `stack dashboard`\n\n### VMs (macOS)\n\n`vm init`, `vm run`, `vm exec`, `vm save`, `vm restore`, `vm list`, `vm stop`, `vm cache`, `vm provision`, `vm cleanup`, `vm self-sign`, `vm validate`, `vm base`, `vm patch`\n\n## Runtime Daemon Connectivity\n\nRuntime-mutating CLI surfaces (`sandbox`, `stack`, `image`, `file`, `lease`, `execution`, `checkpoint`, `build`) use `vz-runtimed` over gRPC/UDS.\n\n- Default socket path is derived from the state DB directory:\n  - `\u003cstate-db-parent\u003e/.vz-runtime/runtimed.sock`\n- Endpoint override:\n  - `VZ_RUNTIME_DAEMON_SOCKET=/absolute/path/to/runtimed.sock`\n- Autostart policy:\n  - `VZ_RUNTIME_DAEMON_AUTOSTART=1` (default) enables daemon cold-start\n  - `VZ_RUNTIME_DAEMON_AUTOSTART=0` disables autostart and fails fast when unreachable\n- Transport selector:\n  - `VZ_CONTROL_PLANE_TRANSPORT=daemon-grpc` (default)\n  - `VZ_CONTROL_PLANE_TRANSPORT=api-http` is accepted; current CLI execution path uses a compatibility connector while full HTTP control-plane routing is tracked in bead `vz-pip6`\n- Sandbox startup defaults (daemon policy):\n  - `VZ_SANDBOX_DEFAULT_BASE_IMAGE=\u003cimage-ref\u003e`\n  - `VZ_SANDBOX_DEFAULT_MAIN_CONTAINER=\u003ccommand-or-container-hint\u003e`\n  - `VZ_SANDBOX_DISABLE_LEGACY_DEFAULT_BASE_IMAGE=1` disables compatibility fallback (`debian:bookworm`)\n- Retention policy defaults (daemon-owned GC):\n  - Untagged checkpoints: max `128` retained, max age `30` days\n  - Tagged checkpoints (`--tag`): retained until explicit deletion\n  - Receipts: max `20_000` retained, max age `14` days\n\n## Architecture\n\n```\nvz-cli\n  |\n  +-- container commands --\u003e vz-oci --\u003e vz-runtime-contract\n  |                              |-\u003e macOS backend (vz-oci-macos, VM-backed)\n  |                              '-- Linux backend (vz-linux-native)\n  |\n  +-- stack commands -----\u003e vz-stack (Compose orchestration)\n  |\n  '-- vm commands (macOS) -\u003e vz (Virtualization.framework wrapper) + vz-guest-agent\n```\n\n## Development\n\n```bash\ncd crates\ncargo build --workspace\ncargo clippy --workspace -- -D warnings\ncargo nextest run --workspace\n```\n\nRuntime API adapter local smoke test:\n\n```bash\ncd crates\ncargo run -p vz-api -- \\\n  --bind 127.0.0.1:8181 \\\n  --state-store-path /tmp/vz-api-state.db \\\n  --daemon-auto-spawn true \\\n  --stack-baseline \\\n  --capability fs_quick_checkpoint\n\n# in another shell\ncurl -s http://127.0.0.1:8181/v1/capabilities\ncurl -s http://127.0.0.1:8181/openapi.json\n```\n\n`vz-api` daemon lifecycle behavior can be tuned for local/dev/operator scenarios:\n\n- `VZ_RUNTIME_DAEMON_AUTOSTART=1` (default) enables cold-start of `vz-runtimed`\n- `VZ_RUNTIME_DAEMON_AUTOSTART=0` disables auto-start and returns `daemon_unavailable` if daemon is not already running\n- `VZ_RUNTIME_DAEMON_SOCKET=/absolute/path/to/runtimed.sock` overrides daemon socket target\n- `VZ_RUNTIME_DAEMON_RUNTIME_DIR=/absolute/path/to/.vz-runtime` overrides runtime data directory used during daemon spawn\n\nSandbox-specific real VM integration validation (macOS ARM64):\n\n```bash\n./scripts/run-sandbox-vm-e2e.sh --suite sandbox\n```\n\nFull VM lanes (runtime + stack + buildkit):\n\n```bash\n./scripts/run-sandbox-vm-e2e.sh --suite all\n```\n\nSee `docs/sandbox-vm-e2e.md` for reproducible debug workflow and artifact paths.\n\nConformance and parity coverage:\n\n- [Runtime primitive conformance matrix](docs/runtime-primitive-conformance.md)\n- [Daemon-only guardrails and fail-close policy](docs/daemon-only-guardrails.md)\n\n## License\n\n[MIT](LICENSE.md)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgpu-cli%2Fvz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgpu-cli%2Fvz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgpu-cli%2Fvz/lists"}