VM - Humane Virtual Environments

Ask for the environment you want, give it a name in plain language, and let vm route to the right engine.

vm run linux as backend
vm shell backend
vm exec backend -- npm test
vm restart backend
vm remove backend

Install

curl -fsSL https://raw.githubusercontent.com/goobits/vm/main/install.sh | bash

Docker is the default engine for Linux and container environments. Tart powers macOS environments on Apple Silicon macOS. Podman is available as an advanced provider override.

Mental Model

You choose the kind of environment:

Kind	Command	Default engine
macOS VM	vm run mac as xcode	Tart
Linux dev env	vm run linux as backend	Docker
Container	vm run container as redis	Docker

Provider names are escape hatches. Day to day, think in mac, linux, and container.

Everyday Workflow

vm run linux as api
vm ssh
vm exec -- cargo test
vm logs --follow
vm restart
vm stop

vm run creates the environment if it does not exist and starts it if it is stopped. vm shell (or vm ssh) creates the configured environment when missing and starts it when stopped. vm exec only starts an existing environment. Omitting a name uses the project default. vm list lists environments for the current project. Use vm list --all for the global inventory. See target selection when a project has multiple environments.

Naming

vm run linux as backend
vm run mac as xcode
vm run container as redis

Naming is intentionally natural language: use as <name>.

If you skip as <name>, the kind becomes the name:

vm run mac
vm shell mac

State

vm save backend as stable
vm revert backend stable
vm package backend --output backend.tar.gz

vm remove removes active environment resources but keeps explicitly saved snapshots.

When You Need More

The daily surface stays small. Specialized workflows are still close by when you need them.

vm config show                         # inspect project defaults
vm config set vm.memory 8192           # tune resources
vm tunnel add 8080:3000 backend        # expose a port
vm doctor                              # diagnose engine issues
vm system update                       # update vm itself

For the complete command surface, see docs/user-guide/cli-reference.md.

Plugins

vm db backup app_db
vm secret interactive
vm plugin install ./plugins/vibe-dev

Plugin-backed workflows stay flat and user-facing. You use vm db, vm fleet, or vm secret; the implementation can still come from plugins.

Configuration

You can ignore configuration until the defaults are not enough. A project can use vm.yaml for durable choices like memory, CPU, workspace path, and default image. vm run creates a starter config when one is missing.

version: '2.0'
provider: docker
project:
  name: backend
  workspace_path: /workspace
vm:
  image: ubuntu:24.04
  memory: 8192
  cpus: 4

Container dependency volumes, bounded /tmp, resource limits, and log rotation are opt-in project settings. See the configuration guide.

Docker Inside Tart

For a full VM that can run Docker, prefer the Linux Tart profile:

vm config preset vibe-tart
vm ssh

+----------------------+
| Apple Silicon Mac    |  M3/M4 + macOS 15+
+----------+-----------+
           | Tart Linux guest
+----------v-----------+
| Linux Dev VM         |  tools, services, /workspace
+----------+-----------+
           | Docker Engine
+----------v-----------+
| Docker Workloads     |  build, compose, test
+----------------------+

Docker runs directly against the Linux guest kernel, so this path does not need Colima. vm ssh creates the Tart environment from vm.yaml when needed and starts it before connecting.

The explicit macOS profile remains available for Xcode or other macOS-only work. Docker inside that macOS guest needs Colima and QEMU TCG software emulation because Tart cannot provide nested virtualization there, so it is the slower fallback.

Development

The repository Makefile owns supported checks. See the Testing Guide for commands, test isolation, and the full local gate.