Skip to content

Running Containers

The Finch CLI aims to support the same top level commands used in other container runtimes, therefore if you have ever used docker run before you will quickly become familiar withfinch run.

Finch leverages containerd and nerdctl to run containers on the lima virtual machine.

Running your first container

finch run is a command that lets you run a container image that either exists in a remote repository or that already exists in the local image store.

To start the hello-finch, sample application that has been built and stored in a remote registry, we can use finch run following by the container image. If you need to authenticate to a container registry see pushing images documentation for instructions.

finch run \
    public.ecr.aws/finch/hello-finch:latest

finch run `
    public.ecr.aws/finch/hello-finch:latest

sudo finch run \
    public.ecr.aws/finch/hello-finch:latest

You should now see the ASCII art in your terminal.

                            @@@@@@@@@@@@@@@@@@@
                        @@@@@@@@@@@@    @@@@@@@@@@@
                      @@@@@@@                  @@@@@@@
                    @@@@@@                        @@@@@@
                  @@@@@@                            @@@@@
                 @@@@@                      @@@#     @@@@@@@@@
                @@@@@                     @@   @@@       @@@@@@@@@@
                @@@@%                     @     @@            @@@@@@@@@@@
                @@@@                                               @@@@@@@@
                @@@@                                         @@@@@@@@@@@&
                @@@@@                                  &@@@@@@@@@@@
                 @@@@@                               @@@@@@@@
                  @@@@@                            @@@@@(
                   @@@@@@                        @@@@@@
                     @@@@@@@                  @@@@@@@
                        @@@@@@@@@@@@@@@@@@@@@@@@@@
                            @@@@@@@@@@@@@@@@@@


Hello from Finch!

Visit us @ github.com/runfinch

Running a container that exposes a port

When running containers on Finch, you can expose a container so that it is reachable from your workstation. To do this, pass the port the application is running on, and the desired external port to the --publish flag for finch run. Note the external port has to be unique, multiple containers can not be exposed on to the same port.

finch run \
    --publish 80:80 \
    public.ecr.aws/nginx/nginx

finch run `
    --publish 80:80 `
    public.ecr.aws/nginx/nginx

sudo finch run \
    --publish 80:80 \
    public.ecr.aws/nginx/nginx

Now in a web browser, you should be able to navigate to localhost and access the running web server container.

Finch Nginx

Common Run Flags

Popular finch run flags which will help you get started include:

  • Automatically clean up a container after it has exited with --rm.

    finch run \
    --rm \
    public.ecr.aws/finch/hello-finch:latest

    finch run `
    --rm `
    public.ecr.aws/finch/hello-finch:latest

    sudo finch run \
    --rm \
    public.ecr.aws/finch/hello-finch:latest

    • Verify that all containers have been removed

      $ finch ps --all

      finch ps --all

      $ sudo finch ps --all

  • Start an interactive session into a container with the tty --tty and the interactive --interactive flags. Assuming your container image has a shell prompt, you will then be placed into the container where you can run commands.

    finch run \
    --interactive \
    --tty \
    public.ecr.aws/docker/library/amazonlinux:latest \
    /bin/bash

    finch run `
    --interactive `
    --tty `
    public.ecr.aws/docker/library/amazonlinux:latest `
    /bin/bash

    sudo finch run \
    --interactive \
    --tty \
    public.ecr.aws/docker/library/amazonlinux:latest \
    /bin/bash

  • Start a container as a background process with the --detach flag.

    finch run \
    --detach \
    --publish 80:80 \
    public.ecr.aws/nginx/nginx

    finch run `
    --detach `
    --publish 80:80 `
    public.ecr.aws/nginx/nginx

    sudo finch run \
    --detach \
    --publish 80:80 \
    public.ecr.aws/nginx/nginx

Next Steps

In this section, you learned how to run containers on Finch