lima-compose

README

lima-compose

Compose for Lima VMs - A thin wrapper around limactl for declarative multi-VM management.

Overview

lima-compose allows you to define and manage multiple Lima VMs using a YAML file. It acts as a thin wrapper around limactl, providing the following capabilities:

• Define multiple VM configurations in a single YAML file
• Execute batch operations (create/delete/start/stop) on all defined VMs
• Display the exact limactl commands being executed

Unlike Docker Compose, lima-compose intentionally provides minimal orchestration features - no service dependencies, no restart policies, and no built-in provisioning. It simply translates YAML definitions into limactl commands.

Features

• Declarative YAML configuration - Define all your VMs in a single file
• Batch operations - Create, start, stop, and delete all VMs with one command
• Transparent execution - See exactly which limactl commands are being run
• Zero learning curve - If you know limactl, you already know lima-compose

Prerequisites

Lima installed and limactl available in PATH

YAML Configuration

The configuration file consists of an instances section where each VM is defined with:

• template (required): The Lima template to use (any form accepted by limactl create)
• args (optional): Command-line arguments passed directly to limactl create

See lima-compose.yaml.example for a working configuration.

Commands

create

Creates all VMs defined in the YAML file.

$ lima-compose create [compose-file]

• Executes limactl create for each instance
• Shows the exact limactl command being run
• Fails if any VM cannot be created

delete

Deletes all VMs defined in the YAML file.

$ lima-compose delete [compose-file]

start

Starts all VMs defined in the YAML file.

$ lima-compose start [compose-file]

stop

Stops all VMs defined in the YAML file.

$ lima-compose stop [compose-file]

If no compose file is specified, lima-compose.yaml or lima-compose.yml is used by default.

version

Shows the version, commit, and build date embedded at build time.

$ lima-compose version

Usage Examples

Basic Workflow

# Create VMs
lima-compose create lima-compose.yaml

# Check status using standard limactl
limactl list

# SSH into a specific VM using standard limactl
limactl shell web-01

# Stop all VMs
lima-compose stop lima-compose.yaml

# Start all VMs
lima-compose start lima-compose.yaml

# Delete all VMs
lima-compose delete lima-compose.yaml

Design Philosophy

lima-compose is intentionally designed as a thin wrapper around limactl:

• Transparent: Every limactl command executed is shown to the user
• Minimal: Only provides multi-VM management, nothing more
• Non-invasive: Does not modify or enhance Lima's functionality
• Predictable: YAML content directly maps to limactl commands

Limitations

By design, lima-compose does NOT:

• Support partial operations (all VMs or none)
• Control startup order or dependencies
• Provide provisioning or configuration management
• Manage VM state beyond what limactl provides
• Hide or abstract Lima's behavior

For individual VM operations, use limactl directly.

License

This project is licensed under the MIT License.