Compose

Commands for managing multi-VM environments defined in VMCompose files. Compose enables declarative orchestration of multiple virtual machines with networking, cloud-init provisioning, resource overrides, and dependency ordering — similar to Docker Compose but for full virtual machines.

up

Create and start all services defined in a VMCompose file. The daemon parses the compose file, creates any defined networks, resolves service dependencies, and starts VMs in the correct order.

vmr compose up [OPTIONS]

Options

Flag	Short	Description
--file <PATH>	-f	Path to the VMCompose file (required)
--project-name <NAME>	-p	Override the project name (defaults to the name field in the compose file)
--detach	-d	Run in detached mode — return immediately after starting all services
--force-recreate		Force recreation of VMs even if they already exist

Examples

vmr compose up -f ./cluster.VMCompose

vmr compose up -f ./cluster.VMCompose -p my-cluster -d

vmr compose up -f ./cluster.VMCompose --force-recreate

TIP

The compose file path must point to a valid VMCompose YAML file. Use vmr compose validate to check the file for errors before deploying. See the VMCompose reference for the full file format specification.

down

Stop and remove all services in a compose project. Networks created by the project are optionally removed as well.

vmr compose down [OPTIONS] [SERVICES...]

Options

Flag	Short	Description
--project-name <NAME>	-p	Project name to tear down (required)
--force	-f	Force stop VMs without graceful shutdown
--volumes	-v	Also remove associated volumes and ephemeral disks

Arguments

Argument	Description
SERVICES	Optional list of specific services to stop (stops all if omitted)

Examples

vmr compose down -p my-cluster

vmr compose down -p my-cluster -f -v

vmr compose down -p my-cluster web-server db-server

WARNING

Using --force sends an immediate destroy signal to each VM without allowing the guest OS to shut down gracefully. Data loss may occur for services with uncommitted writes.

ps

List the status of services in a compose project, showing each service's VM name, image, status, IP address, and creation time.

vmr compose ps [OPTIONS]

Options

Flag	Short	Description
--project-name <NAME>	-p	Project name to inspect (required)
--all	-a	Show all services, including stopped ones

Output Fields

Field	Description
Name	Service name as defined in the compose file
VM Name	Actual libvirt domain name assigned to the service
Image	VM image reference used by the service
Status	Current state (running, stopped, etc.)
IP	IP address assigned to the service (if available)
Created	When the service VM was created
Network ID	Identifier of the attached network

Examples

vmr compose ps -p my-cluster

vmr compose ps -p my-cluster -a

restart

Restart one or more services in a compose project. If no specific services are listed, all services in the project are restarted.

vmr compose restart [OPTIONS] [SERVICES...]

Options

Flag	Short	Description
--project-name <NAME>	-p	Project name (required)
--force	-f	Force restart without graceful shutdown

Arguments

Argument	Description
SERVICES	Optional list of specific services to restart (restarts all if omitted)

Examples

vmr compose restart -p my-cluster

vmr compose restart -p my-cluster web-server

vmr compose restart -p my-cluster -f web-server db-server

validate

Validate a VMCompose file for structural correctness without deploying anything. Reports whether the file is valid and lists the discovered service names.

vmr compose validate [OPTIONS]

Options

Flag	Short	Description
--file <PATH>	-f	Path to the VMCompose file to validate (required)

Output Fields

Field	Description
Valid	Whether the compose file passed validation
Message	Human-readable validation result or error description
Services	List of service names discovered in the file

Examples

vmr compose validate -f ./cluster.VMCompose

TIP

Validation checks include required field presence, value type correctness, valid network modes, valid restart policies, proper CIDR and IP notation in network configurations, and detection of cyclic service dependencies. For editor-level real-time validation, see the LSP component.