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/0.6.2/floki-0.6.2-linux.tar.gz | tar xzvf -

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

$ ./floki --version
floki 0.6.2

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.


Collection of the latest Issues




I would like to propose an enhancement to floki to more easily allow existing environment variables to be passed through from the invoking environment to the floki docker container.

I have increasingly been coming across situations which require authentication, where credentials are typically provided via env vars. I therefore want to make it easy to pass these env vars through from a developer's environment into a floki container.

This is currently possible via docker_switches:

However, this is a bit clunky, particularly if you want to pass multiple variables. It is also potentially non-trivial to update this list with automated tools if you want to add/remove entries.

I therefore propose adding a new key env, which simply takes a list of environment variable names to pass through. This would be expanded internally to a series of -e <env_var_name> parameters for the docker run invocation. Example:


I'm happy to make the code changes if we can agree that this is a desirable feature.




It would be useful to be able to mount a volume from the current directory rather than specifying an absolute path with:


  • -v
  • /absolute/path/to/kube/config:/root/.kube`

Floki is intended to create reproducible containers with the minimum amount of pre-setup. By only allowing absolute paths in volume mounting, a difference in behaviour is created if another user has a different file structure.




In order to make floki easier to test on the Rust side, it might make sense to split floki into a library portion and a binary portion. This issue is to track what code would be in which part.

My naive first take on this:

  • binary:

    • command line parsing
  • library:

    • everything else

Would be interested in hearing thoughts... @rlupton20?




In order to get user switching working appropriately when the upstream Docker image has USER , I have used the following:

Trial and error has revealed that the outer shell cannot have a freeform input, but the inner shell can.




Floki mostly consists of:

  • A command-line interface;
  • A series of subshell commands.

Neither are covered in UT, and by their nature aren't easy to cover with UTs either. This means it's easy to break Floki and have all UTs continue to pass.

Having some FV-style testing of Floki as a whole would be useful for catching this class of bugs, and likely more useful in general than fairly narrow-scoped UTs.




We've got docker-in-docker support, but support for mounting and using the host's docker would be useful too - e.g. for building Docker images for use on the host.




Being dropped out of floki when an init step fails is kind of annoying, but also kind of useful. This boils down to whether the inner commands are linked with ; (permissive) or '&&' (get thrown out on error).




Some build tools like to persist build data to disk. It would be nice if floki allowed build caches created inside the container to persist between container launches, and even across containers in different which might want to share a cache (e.g. Rust builds).

Caches should work even if the user hasn't configured them (as in, they should do something sensible if enabled, and not rely on the users environment), but it may be worthwhile allowing users to set a particular file directory for a cache.




--privileged is the only Docker switch currently needed by our build process in floki. With the recent change to require the "local" option if Docker switches are used it would be useful if that could be an option instead.


Find the latest versions by id

0.9.0 - May 11, 2022

[0.9.0] - 2022-05-11


  • set tls=false for dind

[0.2.0] - 2019-08-10


  • Small tidyups of environment collection module - PATCH
  • Disable TLS in dind to fix failing dind functionality on newer dind:stable images - PATCH


  • Forward host working directory as FLOKI_HOST_WORKDIR - MINOR

[0.1.0] - 2019-05-26


  • Remove forward_tmux_socket - BREAKING
  • Remove --pull switch - BREAKING
  • Remove pull specifications from configuration file - BREAKING
  • Refactor to collect environment at start of day - PATCH
  • Only mount the ssh_agent socket file - BREAKING
  • Start working in the mount_pwd path - BREAKING
  • Rename mount_pwd to mount - BREAKING
  • Enforce reproducibility (override with --local) - BREAKING
  • Move from trim_right to trim_end - PATCH
  • (Refactor) Simplify addition of environment variables to docker run - PATCH
  • Refactor - PATCH
  • Add Travis CI file - PATCH
  • Use 2018 edition of rust. - PATCH
  • Update quicli to 0.4 - PATCH
  • Deploy to GitHub - PATCH
  • Make sh the default shell - BREAKING


  • Make pull a subcommand of floki - MINOR

[0.0.20] - 2019-02-12



  • Expose host user id as FLOKI_HOST_UID - MINOR
  • Expose host user id as FLOKI_HOST_GID - MINOR
  • Allow inner and outer shells to be specified - MINOR

0.8.0 - Jan 25, 2022

0.8.0 - 2022-01-25


  • Change docker in docker image tag from stable-dind to dind


  • Fix up clippy warnings and enforce clippy going forward
  • image_exists_locally now checks that the specified image exists

0.0.16 - 2018-09-10


  • Wrapped common docker errors to make them clearer - PATCH

0.0.15 - 2018-08-08


  • Only kill dind container if we launched it - BUGFIX

0.0.14 - 2018-08-08


  • --pull switch to update images - PATCH


  • Fixup docker-in-docker to allow bind mounts - PATCH

0.0.13 - 2018-08-06


  • docker-in-docker support - PATCH
  • Add ability to forward current user - PATCH

0.0.12 - 2018-07-31


  • Made tmux socket forwarding permissive (doesn't fail if not found) - PATCH

0.0.11 - 2018-07-31


  • Build spec now requires the name as a subkey of build - BREAKING
  • forward_tmux_session -> forward_tmux_socket - BREAKING


  • Rewrite in Rust - PATCH
  • Sphinx docs - PATCH

0.0.10 - 2018-07-25


  • Allow custom docker switches - PATCH
  • Configurable pull policy - PATCH

0.0.9 - 2018-07-12


  • Add a version switch - PATCH


  • Make docker not use sudo - PATCH

0.0.8 - 2018-07-11


  • Empty init defaults to no commands - BUGFIX
  • Make image specification mandatory - PATCH

0.0.7 - 2018-07-10


  • Change how we specify an image to build - PATCH

0.0.6 - 2018-07-10


  • Add option to forward tmux socket - PATCH
  • Add basic configuration validation - PATCH
  • Added ability to specify shell - PATCH
  • Add BSD style help switch - PATCH

0.0.5 - 2018-07-03


  • Config file now command line parameter. Default still ./floki.yaml

0.0.4 - 2018-04-06


  • Allow build container to originate from Dockerfile - PATCH

0.0.3 - 2018-04-06


  • Rename to ssh-agent forwarding field - PATCH

0.0.2 - 2018-04-06


  • Rename to floki to prevent conflicts on pypi - PATCH

0.0.1 - 2018-04-06


  • Initial primitive version


0.7.1 - Dec 08, 2021

[0.7.1] - 2021-12-08


  • Adjust SSH agent forwarding error message
  • Fixed Github releases

0.6.2 - Mar 03, 2021

0.6.1 - Jul 16, 2020

0.6.0 - Jul 15, 2020

dind is broken in this release. Please use 0.6.1.

0.5.0 - May 05, 2020

0.4.3 - Dec 02, 2019

0.4.2 - Dec 02, 2019

0.4.1 - Nov 12, 2019

0.4.0 - Nov 07, 2019

0.3.0 - Oct 01, 2019

0.2.0 - Aug 10, 2019

0.1.0 - May 25, 2019

Information - Updated Jun 23, 2022

Stars: 38
Forks: 16
Issues: 20

Repositories & Extras

Rust port of my CHIP-8 Emulator (interpreted)

cargo run &lt;path-to-ROM-file&gt;

Rust port of my CHIP-8 Emulator (interpreted)

QEMU support using RustSBI

When running cargo qemu, the test kernel will build and run

QEMU support using RustSBI


A CMSIS-DAP firmware for cargo-binutils and run:


Runs embedded programs just like native ones

probe-run is a custom Cargo runner that transparently runs Rust firmware on a

Runs embedded programs just like native ones

Run cargo build to install all dependencies

Run cargo run to play the game

Run cargo build to install all dependencies

Simple Blockchain

cargo run para ejecutar la app, cargo build para crear un ejecutable

Simple Blockchain

Types and traits for http clients

cargo add installed run:

Types and traits for http clients

A game in rust to learn rust and some opengl

Still cargo run to run executable, this main program watches over changes in

A game in rust to learn rust and some opengl

Light weight image library which focus on plotting!

type cargo run --example &lt;example_name&gt; in your terminal to see these example images crafted by our library

Light weight image library which focus on plotting!

little annoy is written in pure Rust

Run cargo run --example demo in your terminal

little annoy is written in pure Rust
Facebook Instagram Twitter GitHub Dribbble