bonk — Docker for cavemen

A guided Rust project. Build a real tool from scratch, one lesson at a time.

Smash a Docker image into a single self-contained executable. No daemon. No registry. No YAML. Just a binary.

bonk alpine:latest
./alpine echo "ooga booga"

Ship anywhere Linux runs — zero runtime dependencies on the target:

bonk python:3.12-slim -o python3
scp python3 someserver:
ssh someserver ./python3 -c "print('hello')"

bwrap and unsquashfs are embedded in the output binary — the target machine needs nothing pre-installed.

1. bonk exports a Docker image, flattens its layers, and builds a SquashFS image with mksquashfs
2. Appends the SquashFS image + static tool binaries (bwrap, unsquashfs) + container config to a small runner binary
3. The output is a single self-contained executable. On first run it writes the embedded .sqfs file to a cache dir and either loop-mounts it (if run with --mount / as root) or extracts it via unsquashfs. Subsequent runs skip both steps.

┌──────────────────────┐
│  bonk-runner ELF     │  small Rust binary
├──────────────────────┤
│  rootfs.sqfs         │  SquashFS image (zstd-compressed)
├──────────────────────┤
│  bwrap (static)      │  ~134 KB embedded container runtime
├──────────────────────┤
│  unsquashfs (static) │  ~1.1 MB embedded SquashFS extractor
├──────────────────────┤
│  config.json         │  entrypoint, cmd, env, workdir
├──────────────────────┤
│  footer (56 bytes)   │  offsets + sizes + magic number
└──────────────────────┘

At runtime:

1. Runner reads itself (/proc/self/exe), locates payload via the footer
2. Extracts bwrap + unsquashfs to /tmp/bonk-<hash>/bin/ (cached)
3. Makes the rootfs available at /tmp/bonk-<hash>/rootfs/ — kernel squashfs loop-mount if privileged (--mount / root), otherwise unsquashfs extraction (both cached; skipped on warm runs)
4. Execs bwrap over the rootfs — overlay filesystem when loop-mounted (read-only lower layer + ephemeral upper), bind-mount when extracted
5. Exits with the container's exit code

Pre-built static binaries are available for every GitHub Release.

x86_64 (Linux)

VERSION=v0.2.0
curl -fsSL https://github.com/avolkha/bonk/releases/download/${VERSION}/bonk-x86_64-unknown-linux-musl -o bonk
curl -fsSL https://github.com/avolkha/bonk/releases/download/${VERSION}/bonk-runner-x86_64-unknown-linux-musl -o bonk-runner
chmod +x bonk bonk-runner
sudo mv bonk bonk-runner /usr/local/bin/

ARM64 (Linux)

VERSION=v0.2.0
curl -fsSL https://github.com/avolkha/bonk/releases/download/${VERSION}/bonk-aarch64-unknown-linux-musl -o bonk
curl -fsSL https://github.com/avolkha/bonk/releases/download/${VERSION}/bonk-runner-aarch64-unknown-linux-musl -o bonk-runner
chmod +x bonk bonk-runner
sudo mv bonk bonk-runner /usr/local/bin/

Both binaries are fully static (musl) — no runtime dependencies on the target machine.

cargo build --release
cp target/release/bonk target/release/bonk-runner ~/.cargo/bin/

Both bonk and bonk-runner must be locatable — either in the same directory or on $PATH.

Build machine:

• Rust toolchain
• Docker (for docker save)
• mksquashfs (from squashfs-tools)

# Ubuntu/Debian
sudo apt install squashfs-tools

Target machine: Linux kernel 3.8+. On Ubuntu 23.10+ and other distros with AppArmor 4.0, unprivileged user namespaces are restricted by default — see AppArmor compatibility below.

# Output name derived from image name
bonk alpine:latest          # → ./alpine

# Custom output path
bonk -o myapp my_image:latest

# Run the generated binary
./alpine                    # launches default CMD
./alpine echo hello         # override CMD
./alpine --help             # show runner help

Pass -e KEY=VALUE (repeatable) to inject environment variables into the container. These are appended after the image's own env vars and override any matching keys. No host environment variables leak in implicitly.

./myapp -e DEBUG=1 -e PORT=8080 -- node server.js
./myapp -e HOME=/data -- bash

./myapp -v /host/data:/data                      # read-write
./myapp -v /etc/hosts:/etc/hosts:ro cat /etc/hosts  # read-only
./myapp -v ./input:/input -v ./output:/output -- process.sh

Following Docker semantics, extra args replace CMD while ENTRYPOINT is preserved:

# Image: ENTRYPOINT ["python3"], CMD ["app.py"]
./myapp              # runs: python3 app.py
./myapp -c "print(42)"  # runs: python3 -c "print(42)"

When --bwrap-path / --unsquashfs-path are omitted, bonk searches in order:

1. BONK_TOOLS_DIR environment variable
2. tools/<arch>/ next to the bonk binary
3. tools/ next to the bonk binary (flat)

bonk/
├── Cargo.toml                    # workspace
├── crates/
│   ├── bonk-common/              # shared types (footer, config)
│   ├── bonk-cli/                 # `bonk` — the build tool
│   │   └── src/
│   │       ├── main.rs           # CLI entry point
│   │       ├── image.rs          # docker save + manifest parsing
│   │       ├── flatten.rs        # layer flattening + whiteout handling
│   │       └── pack.rs           # squashfs build + binary assembly
│   └── bonk-runner/              # embedded runner stub
│       └── src/
│           ├── main.rs           # payload dispatch + cache management
│           ├── mount.rs          # kernel squashfs loop-mount + unsquashfs fallback
│           └── runtime.rs        # bwrap invocation + volume mounts
├── lessons/                      # guided curriculum (see below)
└── tests/
    └── e2e.sh

This repo is structured as a guided Rust curriculum. Each lesson introduces language concepts through a concrete piece of the tool.

dockerc is the closest comparable tool — it also converts Docker images into single self-contained executables with no runtime dependencies. The key architectural difference is in how the rootfs is served at runtime.

Why bonk is faster at runtime: dockerc mounts squashfs via FUSE — every open() and stat() goes user → kernel → FUSE daemon → kernel → back, through two FUSE layers. bonk either loop-mounts the squashfs directly via the kernel squashfs driver (zero FUSE overhead) or extracts to a native directory once; both strategies hit the filesystem at native speed on warm runs.

Where dockerc wins: no one-time setup step required — it mounts on every invocation without needing root.

bonk's privileged path vs. dockerc: sudo ./myapp --mount runs once to set up the kernel mount, then every subsequent ./myapp call runs unprivileged at full speed — no FUSE daemon, no extraction wait.

• Linux only — bwrap is Linux-specific
• No cgroup isolation — no memory/CPU limits
• No multi-container orchestration — single binaries, not a compose replacement
• Cache in /tmp — cache is lost on reboot; first run after reboot re-extracts or re-mounts
• Privileged mount requires sudo — the kernel squashfs loop-mount path needs root; without it bonk falls back to unsquashfs extraction
• Disk usage (extraction path) — rootfs cache uses disk space equal to the uncompressed image; the mount path only stores the .sqfs file

bonk's rootless code path depends on unprivileged user namespaces (clone(CLONE_NEWUSER)). Ubuntu 23.10+ and other distros running AppArmor 4.0 restrict this by default (kernel.apparmor_restrict_unprivileged_userns=1). Because the embedded bwrap binary is extracted to a temporary cache directory with no installed AppArmor profile, the syscall is denied and ./myapp fails silently.

Option A — use the privileged mount path (recommended for Ubuntu VMs):

sudo ./myapp --mount   # one-time setup per reboot; chowns cache back to you
./myapp                # all subsequent runs are unprivileged at full speed

The loop-mount path runs bwrap as root using --unshare-ipc/pid/uts/cgroup rather than --unshare-all, so AppArmor's user-namespace restriction does not apply.

Option B — allow unprivileged user namespaces system-wide:

sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
# Persist across reboots:
echo 'kernel.apparmor_restrict_unprivileged_userns=0' | sudo tee /etc/sysctl.d/99-userns.conf

Option C — use the system bwrap instead of the embedded one:

If bwrap is installed via the system package manager, its distro-provided AppArmor profile grants it the userns capability:

sudo apt install bubblewrap
BONK_BWRAP=/usr/bin/bwrap ./myapp

Commits follow the Conventional Commits spec. This drives the changelog and version bumps:

Apache License 2.0 — see LICENSE for details.