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] [FILE]

Arguments

Argument	Description
FILE	Path to the VMCompose file (defaults to ./VMCompose)

Options

Flag	Short	Description
--project-name <NAME>	-p	Override the project name (defaults to the name field in the compose file, or the directory name)
--detach	-d	Run in detached mode — return immediately after starting all services
--force-recreate		Recreate VMs even if they already exist

Examples

vmr compose up

vmr compose up ./cluster.VMCompose

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

vmr compose up ./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		Also remove the VMs' disk volumes

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 --volumes

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.

list

List all compose projects tracked by the daemon, showing each project's status, service count, and creation time.

vmr compose list [OPTIONS]

Options

Flag	Short	Description
--names-only	-q	Print only project names, one per line

Output Columns

Column	Description
PROJECT	Compose project name
STATUS	Aggregate project status
SERVICES	Number of services in the project
CREATED	When the project was created

Examples

vmr compose list

vmr compose list -q

ps

List the status of services in a compose project.

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 Columns

Column	Description
SERVICE	Service name as defined in the compose file
VM NAME	Actual VM name assigned to the service
STATUS	Current state (running, stopped, etc.)
IP	IP address assigned to the service (if available)
IMAGE	VM image reference used by the service

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 [FILE]

Arguments

Argument	Description
FILE	Path to the VMCompose file to validate (defaults to ./VMCompose)

Output

On success, prints ✓ VMCompose is valid followed by an overview of the parsed document:

• Overview — file path, project name, kind, API version, and service/network counts
• Services — each service with its image, resources, networks, dependencies, restart policy, disk size, and lifecycle
• Networks — each network with its mode, bridge, subnet, gateway, driver, DHCP, and parent device

On failure, prints Validation failed: <reason> and exits with a non-zero status.

Examples

vmr compose validate

vmr compose validate ./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.