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

Writable home directory mount can cause security issues

Your home directory is mounted as writable into the VM. An escaped or privileged container can potentially read and alter the contents of your home directory including your SSH keys, AWS config, and registry credentials.

To disable the home directory mount, you can edit the Lima config file at /Applications/Finch/os/finch.yaml and remove the following lines starting with location: "~" from the mounts section:

mounts:
    - location: "~"
      mountPoint: null
      writable: true
      sshfs:
        cache: true
        followSymlinks: false
        sftpDriver: "openssh-sftp-server"
      9p:
        securityModel: "none"
        protocolVersion: "9p2000.L"
        msize: "128KiB"
        cache: "fscache"

To keep the home directory mount but make it read-only, you can change writable: true to writable: false in the section mentioned above.

This file lives under /Applications, so administrative privileges are required to edit it.

Finch only reads this file when it creates the virtual machine, so an existing virtual machine must be removed and initialized again for the change to take effect:

finch vm stop
finch vm remove
finch vm init

Adding additional disk mounts¶

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

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
```
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.

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
```
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 change the size of the data disk, you can use the datadisk option in ~/.finch/finch.yaml:

datadisk: 100GiB

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.

First make sure the virtual machine has been stopped
```
finch vm stop
```
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.
Next start back up the virtual machine
```
finch vm start
```
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
```