#docker #build-environment #run #yaml #interactive #interactively #configuration

app floki

floki aims to provide reproducible and shareable build tooling by helping you run docker containers interactively from a declarative yaml file

16 releases (5 stable)

1.2.1 Jul 20, 2023
1.0.1 Apr 18, 2023
1.0.0 Sep 12, 2022
0.9.1 Jun 28, 2022
0.4.1 Nov 12, 2019

#162 in Command line utilities

MIT license

1.5K SLoC


Floki was a boatbuilder. Floki now helps you manage interactive containers for building software.

What is floki?

Docker and kubernetes are great ways to run software, and it is often convenient to use the same containers interactively to get a repeatable and complete build environment. However, using these containers for development is not always straightforward.

floki aims to improve the human interface for launching and using interactive docker containers. Instead of remembering or constructing complicated docker run commands, or writing custom scripts to launch docker containers, floki lets you specify what you want from your docker container in a configuration file. You can then get your environment just by running floki. It doesn't replace docker or kubernetes, its an addition to try and improve the human interface for working on a codebase.

This has several advantages over the usual approaches (custom scripts, or, more commonly, leaving it to the user to figure out)

  • an immediate build environment
  • easier to share and on-board new developers
  • a consistent and uniform interface to get a working environment


For installation, and basic usage, see getting started.

Full documentation can be found here.


This assumes you have already installed floki using the installation instructions below.

Suppose we want a build environment based on alpine:latest with a C compiler, and clang tools. Suppose we want to also have SSH credentials available from the host, so we can, for example, authenticate with a private git server.

First create your Dockerfile:

FROM alpine:latest

RUN apk update && apk add alpine-sdk clang openssh

and then add a file called floki.yaml to the root of your codebase:

    name: hello-floki

forward_ssh_agent: true
  - echo "Welcome to the hello-floki build container"

Now run floki. You should see the docker container be built, and you will be dropped into a shell. If you had an ssh-agent running on the host before running floki, you can run ssh-add -l and you should see the same keys loaded as you had on the host.



It's recommended you add your user to the docker group:

$ sudo usermod -a -G docker USERNAME

and logout and in again to pick up the changes.

Alternatively you can run floki (after installation) with sudo -E floki.

Installation from pre-built binaries

Precompiled binaries can be downloaded from the releases page (for linux and OSX).

To obtain curl and extract the latest linux binary directly in your shell, run

$ curl -L https://github.com/Metaswitch/floki/releases/download/1.2.1/floki-1.2.1-linux.tar.gz | tar xzvf -

You should be able to run floki from your working directory:

$ ./floki --version
floki 1.2.1

Move it onto your path to run it from anywhere. E.g.

$ mv floki /usr/local/bin/


Installation from cargo

floki can also be installed directly from cargo.

$ cargo install floki

Handy features

  • Forwarding of ssh-agent (useful for authenticating with remote private git servers to pull private dependencies)
  • Docker-in-docker support
  • Forwarding of host user information (allows non-root users to be added and used).
  • volumes (shared, or per-project) for e.g. build caching.


Contributors will need to sign their commits to acknowledge the DCO


See issues.


~293K SLoC