Skip to content

Managing Finch Storage

Disk Mounts

To allow containers and container image builds to access files from the local workstation within the virtual machine, a users home directory (on macOS this is /Users/<username>) is automatically mounted into the machine by Lima.

To demonstrate this, in an empty directory on the workstation you can create a hello file, and then mount it into the container with the --volume command.

touch hello

finch run \
   --volume $PWD:/data \
   public.ecr.aws/amazonlinux/amazonlinux:2 \
   ls /data

You should see the file you just created.

hello

Adding additional disk mounts

For users wanting to mount additional directories in the virtual machine, they can specify additional mounts in the Finch Configuration.

  1. Open the Finch configuration in a text editor ~/.finch/finch.yaml and add the relevant paths for the local directory on your workstation.

    cpus: 3
    memory: 4GiB
    additional_directories:
      - "/Volumes/test"
    

    Note

    If your username doesn't match your home directory name, you may need to add /Users/<username> to the additional_directories list. This can help avoid permission issues when building Docker images or accessing files within containers.

    additional_directories:
        - "/Users/<username>"
    

    1. Restart the virtual machine to pick up the changes in the mounts.
    finch vm stop
    finch vm start
    
  2. Once the virtual machine has been restarted you can test this mount. First create a temporary directory and file in this new disk location.

    mkdir /Volume/test/testdir
    touch /Volume/test/testdir/hello
    

    Then mount the volume into a new container.

    finch run \
       --volume /Volume/test/testdir:/data \
       public.ecr.aws/amazonlinux/amazonlinux:2 \
       ls /data
    

    You should see the file you just created.

    hello
    

Disk Mount Technology

By default the disk is mounted into the virtual machine using sshfs. For users running macOS 13 or later, if you switch to Apple's Virtualization Framework in the Finch Configuration, the disk mounts will instead leverage the more performant virtiofs.

  1. Open the Finch configuration in a text editor ~/.finch/finch.yaml and add the key vmType with the value vz.

    cpus: 3
    memory: 4GiB
    vmType: vz
    
  2. Restart the virtual machine to pick up the changes in the virtualization technology.

    finch vm stop
    finch vm start
    

Disk Size

By default the Finch virtual machine will have a disk capacity of 50GB, even though you may have more disk space available on the local workstation. As you start to build container images and run containers, this disk space may reach capacity.

To free up disk space you can delete stale container image layers with:

finch image prune

You can also free up disk by delete all container images without a container attached with:

finch image prune --all

Note

Running finch system prune cleans up unused containers, images, volumes, and networks inside the VM, but it does not reduce disk usage on the host OS. To reclaim the freed space on your Mac, follow these steps:

Log in to the VM shell:

export LIMA_HOME=/Applications/Finch/lima/data
/Applications/Finch/lima/bin/limactl shell finch

Run fstrim inside the VM:

sudo fstrim -v /mnt/lima-finch

Increasing the size of the Data Disk

To expand the virtual machine disk size above 50GB, you can use the Finch VM disk resize command.

  1. First make sure the virtual machine has been stopped

    finch vm stop
    
  2. Resize the virtual machine disk using the finch vm disk resize command.

    finch vm disk resize --size <size>
    

    For example, to increase to 100GiB:

    finch vm disk resize --size 100GiB
    

    Note: Disk size can only be increased, not decreased. This is due to limitations with the underlying sparse disk format used by QEMU, which does not support shrinking after expansion.

  3. Next start back up the virtual machine

    finch vm start
    
  4. To validate the change has been successful, shell into the virtual machine, checks the disk size with df -h.

    export LIMA_HOME=/Applications/Finch/lima/data
    
    /Applications/Finch/lima/bin/limactl shell finch df -H