Skip to content

Finch Configuration

Finch has a configuration file stored at ~/.finch/finch.yaml on macOS or %LocalAppData%\.finch\finch.yaml on Windows. This configuration file abstracts away the virtual machine, Lima and Hypervisor configuration.

Each time the finch.yaml configuration is updated, the virtual machine will need to be restarted for the change to take effect.

finch vm stop
finch vm start

Example finch.yaml file:

cpus: 3
memory: 4GiB
bootdisk: 100GiB
datadisk: 50GiB
snapshotters:
  - "overlayfs"
creds_helpers:
  - "ecr-login"
additional_directories:
  - "/Volumes/mydir"
vmType: vz
rosetta: true
dockercompat: true

Parameters

Many of Finch's configuration options are currently macOS only, and this will be indicated below. On Windows, WSL has its own set of configuration options options available here.

  • cpus (macOS only): The number of logical CPUs to attach to the virtual machine. The default is determined dynamically based on the resources available using 0.25 * total_cpu_cores, with a minimum value of 2.

  • memory (macOS only): The amount of memory to attach to the virtual machine. The default is determined dynamically based on the resources available using 0.25 * total_memory, with a minimum value of 2GiB.

  • bootdisk (macOS only): The size of the boot disk attached to the virtual machine, which holds the guest operating system. Must be greater than 10GiB. Default is 100GiB.

  • datadisk (macOS only): The size of the data disk attached to the virtual machine, where container images, containers, and volumes are stored. Must be greater than 10GiB. Default is 50GiB. Both disks are sparse and can only be grown once created. See disk management for more details.

  • snapshotters: The list of containerd snapshotters that will be installed and configured on to the virtual machine. For more information on lazy loading snapshotters see Lazy Loading. Supported values: soci, overlayfs. When this field is omitted Finch will use the overlayfs snapshotter. By default this field is omitted.

  • creds_helpers: The list of credential helpers that will be installed and configured automatically on finch vm init or finch vm start. For more information see Registry Authentication. Supported values: ecr-login. By default this field is omitted.

  • additional_directories (macOS only): By default Finch will mount the users home directory into the virtual machine. To mount additional directories from macOS into the virtual machine, specify them here. See disk management for more details. Default is []

  • vmType: The hypervisor to use for the virtual machine.

    • macOS
    • Windows
      • The only supported vmType for Windows is wsl2

  • rosetta: (macOS only): The emulation layer to use when running container images or processes on an architecture not native to the machine. If value is set to false, the emulation is provided by QEMU. If value is set to true, Apple's Rosetta framework is used. Rosetta can only be used if vmType: vz. When vmType: vz is set, without specifying rosetta, rosetta will default to true. Otherwise, the default is false

    Rosetta requires an Apple Silicon machine running macOS 26 Tahoe or later. On macOS 15 Sequoia or earlier leave rosetta unset or set it to false to use QEMU emulation instead. See the macOS installation prerequisites for more details.

  • dockercompat: activates finch functionality to accept docker-compatible arguments and return docker-like responses for a limited set of docker commands. Specifically, Finch will convert the Docker invocation into compatible nerdctl commands and arguments when possible. This option is required for running DevContainers on Finch.

  • vmnet (macOS only): Enables shared networking for the virtual machine, allowing the VM to obtain a routable IP address on the host network. The behavior depends on the vmType:

    • vmType: qemu: Installs socket_vmnet to provide a bridged network interface. finch vm init will require a one-time sudo prompt to install the socket_vmnet binary to /opt/finch/ and configure sudoers. Subsequent VM starts do not require sudo.
    • vmType: vz: Uses Apple's native vzNAT to provide VM networking with no privilege escalation required.

When disabled or unset (the default), the VM uses user-mode networking (slirp for qemu, or the default vz network stack). Default is false.