# runfinch/finch: a native container client that wraps Lima, containerd and nerdctl

> Finch bundles Lima, containerd, nerdctl and BuildKit behind one installer and one CLI, so macOS, Windows and Linux developers can build and run OCI images without assembling the stack themselves. It is a developer tool, not a production runtime.

**runfinch/finch** — The Finch CLI is an open source client for container development

- Repository: https://github.com/runfinch/finch
- Website: https://www.runfinch.com
- Stars: 4,067 · Forks: 117
- Language: Go
- License: Apache-2.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/runfinch-finch

## What Finch actually assembles, and who it is for

Finch is a client, not a container engine. The README describes it as "an open source client for container development" whose installer ships "a minimal native client along with an opinionated distribution of other open source components." The components are named explicitly: nerdctl handles build, run, push and pull; containerd manages containers; BuildKit performs OCI image builds; and all of it runs inside a virtual machine managed by Lima. The go.mod file confirms the dependency set, pinning github.com/containerd/nerdctl/v2, github.com/lima-vm/lima and github.com/lima-vm/lima/v2 alongside the Docker CLI and Docker daemon libraries that nerdctl draws on.

The target user is a developer on macOS or Windows who wants Linux containers without choosing among runtimes, VM managers and build backends. The README is direct about the scope: Finch "doesn't implement 100% of the upstream commands," but points at the nerdctl Command Reference as the documentation starting point. That sentence is the honest description of the product. You are adopting nerdctl's interface with a Finch-managed VM underneath, not a new command language.

The README also draws a boundary that matters more than any feature list. Finch "is a developer tool and is not meant for use in production environments, especially one running multi-tenant workloads," and the VM it manages on macOS and Windows "does not create a security boundary." Anyone evaluating Finch as a lightweight alternative to a hardened container host should stop at that line.

## How the Lima VM, containerd and BuildKit fit together

The architecture is layered, and each layer is a separate upstream project. Finch's own binary is the top layer: a Go CLI built with spf13/cobra, per go.mod, that translates user commands into calls against the lower layers. On macOS and Windows, Lima boots a Linux virtual machine; inside that VM, containerd runs as the container runtime and BuildKit handles image builds. On Linux, the README states the prerequisite is a system "capable of running containerd 1.7.x (generally, this means at least Linux kernel 4.x)," which implies the VM layer is not part of the Linux path in the same way.

Data flow for a build follows the standard OCI route. finch build reads a Dockerfile, hands it to BuildKit, and produces an OCI image, which the README describes as "a special sort of recipe for creating an image." finch run pulls an image if it is absent locally, then creates and runs a container through containerd. finch images lists what is present locally. The --platform option threads through both: on an Apple Silicon machine, --platform=amd64 makes the run execute x86-64 processes inside the container, and the same flag applies to builds for multiplatform output.

The repository layout reflects this split. There are separate Makefile.darwin and Makefile.windows files, an installer-builder directory, an msi-builder directory for the Windows package, and winres for Windows resources. A finch@.service unit file and finch.yaml.d directory sit at the top level, alongside networks.yaml. The presence of both a systemd unit and a YAML drop-in directory suggests the Linux install path is expected to be managed as a service rather than only as a user-run binary.

## Installing Finch on macOS, Windows and Linux

On macOS, the prerequisites listed are macOS Catalina (10.15) or higher, an Intel or Apple Silicon M1 system, and a recommended minimum of 2 CPU and 4 GB memory. The README gives two routes: download a release package for your architecture from the GitHub releases page and double click it, or use Homebrew.

```bash
brew install --cask finch
```

The Homebrew cask installs the same release artifact without the manual download step. After installation, the VM still has to be created.

On Windows, the prerequisites are Windows 10 version 2004 or higher (Build 19041 and higher), an AMD64-based system, and WSL 2 installed via wsl --install. The README points at an MSI installer from the releases page. Windows requires an explicit initialization step that macOS does not document in the same way.

```bash
finch vm init
INFO[0000] Initializing and starting Finch virtual machine...
..
INFO[0067] Finch virtual machine started successfully
```

The README states this initial setup "usually takes about a minute," and the sample output shows roughly 67 seconds between the first and last log line. Once the VM is running, a first container is one command. The README uses a public ECR image for the smoke test.

```bash
finch run --rm public.ecr.aws/finch/hello-finch
```

The --rm flag deletes the container after it exits. To build something, the repository ships a sample under contrib/hello-finch.

```bash
git clone https://github.com/runfinch/finch.git
cd finch/contrib/hello-finch
finch build . -t hello-finch
```

On Linux, the README states installers are currently "packaged and distributed on Amazon Linux." For other distributions it directs you to download the binary from the releases page and install and configure dependencies following the convention in contrib/packaging/rpm/finch.spec, with detailed instructions on runfinch.com. That is a real asymmetry: the macOS and Windows paths are one-command installs, and the generic Linux path expects you to read a spec file.

## The command surface is nerdctl's, with the gaps that implies

Finch does not reimplement container operations. The README says that for "the core build/run/push/pull commands, Finch depends upon nerdctl to handle the heavy lifting," and that while the most common commands are in place, coverage is not complete. The practical consequence is that your muscle memory from Docker transfers only as far as nerdctl supports it. When a flag or subcommand is missing, the answer is not in Finch's documentation, because Finch's documentation largely defers to nerdctl's command reference.

This is a deliberate trade-off and it cuts both ways. You inherit nerdctl's behavior, including its differences from the Docker CLI, without a Finch-specific compatibility layer to smooth them over. The README frames the bundling as a way to "help promote other projects by making it easy to install and use them," which is an accurate description of the intent but also a statement that Finch is not trying to be the definitive interface. If your workflow depends on a Docker CLI feature that nerdctl has not implemented, Finch is the wrong layer to fix it in.

The version pinning in go.mod reinforces how tightly coupled this is. The module requires github.com/containerd/nerdctl/v2 v2.2.2 and both github.com/lima-vm/lima v1.2.3 and github.com/lima-vm/lima/v2 v2.1.3. Upstream changes in nerdctl or Lima land in Finch through dependency bumps, which means the CLI's behavior can shift with a release that looks like a routine version increment.

## Where Finch is the wrong tool

The clearest limitation is stated by the project itself. Finch is a developer tool and is not meant for production environments, "especially one running multi-tenant workloads." The VM that Finch manages on macOS and Windows "does not create a security boundary and exists for the sole purpose of running Linux containers on macOS and Windows." If your threat model assumes the container runtime isolates untrusted tenants, Finch's architecture does not provide that on those platforms, and no amount of configuration changes the statement in the README.

A second constraint is platform coverage. macOS support targets Catalina (10.15) or higher with newer versions "tested on a best-effort basis," which is a softer commitment than a supported-versions matrix. Windows requires WSL 2 and an AMD64 system, so ARM Windows is out of the documented scope. On Linux, packaging is distributed for Amazon Linux, and other distributions are expected to install the binary and configure dependencies themselves following the RPM spec convention.

A third is the documentation gap the README admits to: "The project will in the near future have a more full set of documentation and tutorials." Until that arrives, users new to containers are working from a short README plus the nerdctl reference. For an experienced container developer that is sufficient. For a team standardizing onboarding material, it means writing your own.

## Finch against installing Lima and nerdctl yourself

The obvious alternative is to install the same components directly: Lima for the VM, nerdctl for the CLI, containerd underneath, and BuildKit for builds. The difference is not capability, since Finch is built from those projects. The difference is who owns the integration.

Assembling the stack yourself gives you control over versions, VM configuration and upgrade timing, and it works on any platform Lima supports rather than the ones Finch packages for. The cost is that you maintain the wiring: the VM definition, the containerd configuration, the nerdctl-to-VM connection, and the BuildKit setup. Finch's value proposition is that its installer ships "an opinionated distribution" of these components, so the wiring arrives tested as a unit.

Finch also adds things that are not simply upstream defaults. The Makefile injects version metadata at build time through -X flags into pkg/version and pkg/config, including a SociVersion and architecture-specific SHA256 sums, and the repository carries a benchmark directory with published benchmark results linked from the README badge. A hand-assembled stack would need equivalent plumbing to report versions and to pin the same artifacts.

The honest comparison: choose Finch when you want the integration maintained for you and you accept its platform list and its nerdctl-shaped command surface. Choose the manual route when you need a platform Finch does not package for, or when you need to control the VM and runtime configuration more precisely than an opinionated distribution allows.

## Licence, upgrades and what maintenance costs

Finch is Apache-2.0, and the repository carries a NOTICE file alongside the LICENSE, which is the standard Apache-2.0 pattern for attributing bundled or derived work. Because Finch distributes other open source components, the licence obligations do not stop at Finch's own code. The Makefile defines a LICENSEDIR variable and the build depends on github.com/google/go-licenses, which indicates the project collects licence files as part of its build process. If you redistribute Finch or an image built with it inside a product, the licence set of the bundled components is the thing to review. That is a factual observation about the build, not legal advice.

Upgrades are release-based. The repository uses release-please, visible in .release-please-manifest.json and release-please-config.json, and publishes a CHANGELOG.md. Recent releases include v1.19.0 on 2026-09-16, v1.18.0 on 2026-08-20 and v1.17.2 on 2026-06-30. The last push to the repository was on 2026-09-18. The upgrade cost that matters is not the binary swap but the VM: because Finch pins Lima and nerdctl versions in go.mod and ships them as a unit, a Finch upgrade can move the VM image and the container runtime together. The README does not document rollback, so pinning a specific release and keeping the installer for it is the only documented way back.

There is also a Linux-specific maintenance surface. The repository contains a finch@.service systemd unit, a finch.yaml.d configuration drop-in directory, and a networks.yaml file. Operators installing on Linux through the RPM path are managing a service, not just a CLI on their PATH.

## Conclusion

Adopt Finch if you want a single installer that puts Lima, containerd, nerdctl and BuildKit on a developer laptop and you are content to use nerdctl's command surface rather than every Docker flag. Do not adopt it for production or multi-tenant hosts: the README states the managed virtual machine on macOS and Windows is not a security boundary, and Linux packaging is distributed for Amazon Linux, with other distributions expected to install the binary and configure dependencies following contrib/packaging/rpm/finch.spec. Before rolling it out, run finch vm init on a target machine and confirm the VM starts, then check the release notes for the version you pin, since the changelog is the only upgrade record the repository publishes.

## FAQ

### How do I install runfinch/finch?

Download a release package for your architecture from the project's GitHub releases page and double click it, or install the Homebrew cask with brew install --cask finch. The README lists macOS Catalina (10.15) or higher, an Intel or Apple Silicon M1 system, and a recommended minimum of 2 CPU and 4 GB memory as prerequisites.

### How do I set up runfinch/finch after installing it?

On Windows, and per the README's example output, run finch vm init once to initialize and start the Finch virtual machine; the README states this initial setup usually takes about a minute. Once the VM is running, finch run --rm public.ecr.aws/finch/hello-finch runs a test container.

### How do I use runfinch/finch to run a container and build an image?

Use finch run with the image reference, and finch build with a Dockerfile directory and a -t tag. The README's build example clones the finch repository, changes into contrib/hello-finch, and runs finch build . -t hello-finch; finch images then lists locally pulled and built images.

## Sources

- [License: Apache-2.0](https://github.com/runfinch/finch/blob/main/LICENSE)
- [Project website](https://www.runfinch.com)
- [README](https://github.com/runfinch/finch/blob/main/README.md)
- [Releases](https://github.com/runfinch/finch/releases)
- [runfinch/finch on GitHub](https://github.com/runfinch/finch)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/runfinch-finch