DOCSEARCHbyAlgolia
Submit Docs

Finch Documentation

repository·main·Indexed 26 days ago

https://github.com/runfinch/finch

Finch is an open-source client for container development that provides a native interface for building, running, and pushing containers. It integrates nerdctl, containerd, and BuildKit within a virtual machine managed by Lima. Supported on macOS, Windows, and Linux, Finch allows users to build OCI images, run containers on specific architectures, and manage container configurations with compatibility for Docker-like commands.

Tokens
35.8K
Snippets
107
Records
236
Agent score
85%

What's inside Finch

  1. Manage images with finch image

    main

    The finch image command is used to manage container images, including building, pulling, pushing, listing, and removing them. It supports standard registry protocols as well as ipfs:// and ipns:// schemes for IPFS-based image management.

    finch image [flags]

  2. Automatic health check scheduling with systemd

    main

    On Mac OS, Windows, and Linux systems with systemd, Finch automatically manages health check execution via systemd timer units (through nerdctl). This ensures reliable scheduling without a persistent daemon.

    Health Statuses:

    • starting: During container initialization.
    • healthy: When health checks are passing.
    • unhealthy: After the specified number of consecutive failures.

  3. Finch Command Compatibility

    main

    Finch commands and options are largely compatible with nerdctl. It supports common container workflows including volume management, network management, and Docker Compose support.

    To enable the translation of Docker-like arguments into compatible nerdctl commands, ensure dockercompat: true is set in your finch.yaml configuration file.

  6. Install Finch on Linux

    main

    Finch installers are primarily packaged for Amazon Linux. For other Linux distributions, download the binary from the GitHub releases page and manually install/configure dependencies following the finch.spec convention.

    Prerequisites:

    • Linux system capable of running containerd 1.7.x (typically Linux kernel 4.x or higher).

  7. Enable PowerShell autocompletion for Finch

    main

    You can generate and load autocompletion scripts for PowerShell to improve your CLI experience.

    To enable completions for your current shell session only, run:

    finch completion powershell | Out-String | Invoke-Expression

    To enable completions permanently for every new session, add the command above to your PowerShell profile script.

  9. Use SOCI for lazy-pulling images

    main

    SOCI allows for lazy-loading images by using a SOCI index, which enables accessing parts of an image layer without fully unpacking it. This significantly improves container start-up times, especially for large images.

    Requirements:

    • For pull and run operations: finch >= 0.8.0
    • For push operations: finch >= 0.9.0

    Note: To benefit from SOCI, the image must have a SOCI index. Finch does not yet support creating SOCI indices; you must use images that already contain them (e.g., from the AWS ECR Gallery) or create them using external tools like the ECR SOCI index builder.

  10. Build Finch Debian packages

    main
    Use the package.sh script to build a Finch Debian archive (.deb). The script can build for amd64 or arm64 architectures. By default, running the script without arguments will build for both architectures and set the version to 0.0.0. Note that building requires internet access to download necessary sources. The resulting packages are moved to the _output/deb/ directory.

  11. Copy files/folders with finch cp

    main

    Use finch cp to copy files or folders between a running container and the local filesystem.

    Requirements:

    • tar must be installed on the host machine (not inside the container).
    • Using GNU tar is recommended.

    Environment Variable:

    • You can specify the path to the tar binary by setting the $TAR environment variable.

    Usage Patterns:

    • Container to Host: finch cp [flags] CONTAINER:SRC_PATH DEST_PATH
    • Host to Container: finch cp [flags] SRC_PATH CONTAINER:DEST_PATH
    • Using Standard Input/Output: Use - to represent stdin or stdout.

  12. Generate fish shell autocompletions for Finch

    main

    You can generate autocompletion scripts for the fish shell to improve your CLI experience.

    To load completions immediately in your current shell session, pipe the output to source.

    To make completions permanent for every new fish shell session, redirect the output to your fish completions directory. You must start a new shell for the changes to take effect.