Configuration File Reference

Each macpine instance has its own configuration stored in a config.yaml file located within its instance directory at ~/.macpine/<instance-name>/config.yaml.

You can edit this file directly or use the alpine edit <instance-name> command. Changes require an instance restart (alpine restart <instance-name>) to take effect.

Example config.yaml

alias: instance-name
image: alpine_3.20.3-aarch64.qcow2
arch: aarch64
cpu: "2"
memory: "2048"
disk: 10G
mount: "/Users/user/Documents"
port: "8080,9090u,10010:10020"
sshport: "20022"
sshuser: root
sshpassword: "raw::root"
rootpassword: "raw::pass"
macaddress: aa:bb:cc:dd:ee:ff
location: /Users/user/.macpine/instance-name
vmnet: false
tags:
    - foo
    - bar

Parameter Reference

Key Type Description
alias string The name of the instance. Do not modify directly; use alpine rename instead.
image string The name of the QCOW2 disk image file to use, located in ~/.macpine/cache.
arch string The CPU architecture of the VM. Can be aarch64 or x86_64.
cpu string The number of CPU cores to allocate to the VM.
memory string The amount of RAM in megabytes (MB) to allocate to the VM.
disk string The size of the virtual disk. Suffixes K, M, and G are supported (e.g., 20G).
mount string An absolute path to a directory on the host to share with the VM. It will be mounted under /mnt/ inside the guest. Leave empty to disable.
port string A comma-separated string for forwarding ports from the host to the guest. See Port Forwarding & SSH for syntax.
sshport string The host port to forward to the VM's SSH server (port 22).
vmnet boolean If true, enables Apple's vmnet-shared networking mode, giving the VM its own IP. Requires sudo. If false (default), uses SLIRP networking with port forwarding.
machineip string The IP address of the machine. Automatically populated when using vmnet-shared mode. Initially localhost for SLIRP mode.
sshuser string The username for SSH connections. Defaults to root.
sshpassword string The credential for the sshuser. See SSH Credentials below.
rootpassword string (Optional) The credential for the root user, only needed if sshuser is not root.
macaddress string The unique MAC address for the VM's network interface. Automatically generated.
location string The absolute path to the instance's directory on the host. Do not modify directly; use alpine rename instead.
tags list of strings A list of tags for organizing and managing the instance.

SSH Credentials

macpine supports several backends for storing SSH credentials, configured via the sshpassword string.

  • raw (Default): The password is a plain string.
  • sshpassword: "raw::root"

  • For backward compatibility, a value without a prefix is treated as a raw password: sshpassword: "root"

  • env: The password is read from a host environment variable. This is more secure than storing it in the file.

  • sshpassword: "env::VM_PASSWORD" (Reads the password from the $VM_PASSWORD environment variable)

  • ssh: Uses an ssh-agent for key-based authentication. This is the most secure method.

  • sshpassword: "ssh::my-vm-host" (Uses the key configured for my-vm-host in your ~/.ssh/config file)