The Finch CLI is an open source client for container development
The Finch CLI is an open source client for container development
Finch is an open source client for container development. Its simple installer provides a minimal native client along with an opinionated distribution of other open source components. Rather than creating even more options to reason about and choose from, Finch aims to help promote other projects by making it easy to install and use them, while offering a simple native client to tie it all together.
Finch provides a simple client which is integrated with nerdctl. For the core build/run/push/pull commands, Finch depends upon nerdctl to handle the heavy lifting. It works with containerd for container management, and with BuildKit to handle Open Container Initiative (OCI) image builds. These components are all pulled together and run within a virtual machine managed by Lima.
With Finch, you can leverage these existing projects without chasing down all the details. Just install and start running and building your containers!
The project will in the near future have a more full set of documentation and tutorials. For now let's get started here. As mentioned above, finch integrates with nerdctl. While Finch doesn't implement 100% of the upstream commands, the most common commands are in place and working. The nerdctl Command Reference can be relied upon as a starting point for documentation.
[!IMPORTANT] Please note that Finch is a developer tool and is not meant for use in production environments, especially one running multi-tenant workloads. The virtual machine 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.
To get started with Finch on macOS, the prerequisites are:
Download a release package for your architecture from the project's GitHub releases page, and once downloaded double click and follow the directions.
Installing Finch via brewbrew install --cask finch
To get started with Finch on Windows, the prerequisites are:
wsl --install)Download an MSI installer from the project's GitHub releases page, and once downloaded double click and follow the directions.
Once the installation is complete, finch vm init is required once to set up the underlying system. This initial setup usually takes about a minute.
finch vm init
INFO[0000] Initializing and starting Finch virtual machine...
..
INFO[0067] Finch virtual machine started successfully
To get started with Finch on Linux, the prerequisites are:
Currently, Finch installers are packaged and distributed on Amazon Linux. If you are not using Amazon Linux, you can download the binary from the GitHub releases page and install/configure the dependencies, following the convention in the finch.spec file. Detailed instructions are available on runfinch.com.
You can now run a test container. If you're familiar with container development, you can use the run command as you'd expect.
finch run --rm public.ecr.aws/finch/hello-finch
If you're new to containers, that is so exciting! Give the command above a try after you've installed and initialized Finch. The run command pulls an image locally if it's not already present, and then creates and runs a container for you. Note the handy --rm option will delete the container instance once it's done executing.
To build an image, try a quick example from the finch client repository.
git clone https://github.com/runfinch/finch.git
cd finch/contrib/hello-finch
finch build . -t hello-finch
..
Again if you're new to containers, you just built a container image. Nice!
The build command will work with the build system (the Moby Project's BuildKit in Finch's case) to create an OCI image from a Dockerfile, which is a special sort of recipe for creating an image. This image can then be used to create containers. You can see your locally pulled and built images with the finch images command.
Finch makes it easy to build and run containers across architectures with the --platform option. When used with the run command, it will create a container using the specified architecture. For example, on an Apple Silicon M1 system, --platform=amd64 will create a container and run processes within it using an x86-64 architecture.
uname -ms
Darwin arm64
finch run --rm --platform=amd64 public.ecr.aws/amazonlinux/amazonlinux uname -ms
Linux x86_64
You can also use the --platform option with builds, making it easy to create multiplatform images.
We have plans to create some more documentation and tutorials here geared toward users who are new to containers, as well as some tips and tricks for more advanced users. For now, if you're ready to kick the tires, please do! You'll find most commands and options you're familiar with from other tools to present, and as you'd expect (or, as they are documented upstream with nerdctl). Most of the commands we use every day are covered, including volume and network management as well as Compose support. If Finch doesn't do something you want it to, please consider opening an Issue or a Pull Request.
The installer will install Finch and its dependencies in its own area of your system, and it can happily coexist with other container development tools. Finch is a new project and not meant to be a direct drop-in replacement for other tools. Therefore, we don't recommend aliasing or linking other command names to finch.
Finch has a simple and extensible configuration.
A configuration file at ${HOME}/.finch/finch.yaml will be generated on first run. Currently, this config file has options for system resource limits for the underlying virtual machine. These default limits are generated dynamically based on the resources available on the host system, but can be changed by manually editing the config file.
For a full list of configuration options, check the finch struct for macOS.
An example finch.yaml looks like this:
…
A configuration file at $env:LOCALAPPDATA\.finch\finch.yaml will be generated on first run. Currently, this config file does not have options for system resource limits due to limitations in WSL.
For a full list of configuration options, check the finch struct for windows.
An example finch.yaml looks like this:
…
This section contains frequently-asked questions regarding working with Finch.
LIMA_HOME=/Applications/Finch/lima/data /Applications/Finch/lima/bin/limactl shell finch
wsl -d lima-finch
See Debugging Finch for common debugging scenarios.
Finch makes a best effort to follow semantic versioning. Generally speaking, all minor version upgrades should be backwards compatible. With that said, we do not make any guarantees. Please let us know if anything breaks!
We are excited to start this project in the open, and we'd love to hear from you. If you have ideas or find bugs please open an issue. Please feel free to start a discussion if you have something you'd like to propose or brainstorm. Pull requests are welcome, as well! See the CONTRIBUTING doc for more info on contributing, and the path to reviewer and maintainer roles for those interested.
As the project gets a bit of momentum, maintainers will start creating milestones and look to establish a regular release cadence. In time, we'll also start to curate a public roadmap from the community ideas and issues that roll in. We already have some ideas, including:
If you'd like to chat with us, please find us in the #finch channel on the CNCF slack.
If you encounter anything that seems wrong, please check out our issues tab first — someone may have already encountered your problem! If it's there, please add to the existing issue thread.
If you can't find an existing issue, feel free to open a new one. As a remninder, anything related to security should NOT go through regular reporting channels. Please refer to Security for guidance on how to report such issues.
No open issues yet, or sync has not completed.