dev-biksa: Reusable Distrobox Dev Containers

This project provides a collection of reusable, Debian-based development containers tailored for use with Distrobox and Podman.

By utilizing a tiered image hierarchy (a base image with shell utilities and agentic AI tooling extending to language-specific toolchain layers), this project provides a fast, isolated, and highly integrated development environment that shares home directory and configuration files seamlessly with the host system.

By transitioning from Alpine to Debian Slim (debian:bookworm-slim), this setup provides a lightweight footprint (~30MB base compressed) combined with native glibc library compatibility. This solves all relocation/dynamic loading library failures for pre-compiled developer utilities and agent runtimes.

Included Tooling

• base Layer:
  • Core integration: bash, sudo, passwd, findutils, util-linux, procps, unzip
  • Networking & files: curl, wget, tar, ca-certificates
  • Editors & Search: neovim, luajit (scripting), lua-check (linter), git, ripgrep (rg), less, bc, ncurses-bin
  • AI Agent CLIs: agy (Google Antigravity CLI) and opencode (OpenCode CLI)
• lua-dev Layer:
  • Lua environment: luajit + lua-check (from base), with lua-language-server (LSP) and stylua (formatter) precompiled system-wide.
• c-dev Layer:
  • C/C++ environment: build-essential (gcc/g++, make), clang, clangd (Neovim LSP), cmake, and ninja-build.
• go-dev Layer:
  • Go environment: Go toolchain (go 1.26.5), standard tools (gopls LSP, dlv debugger), and build-essential for CGO support.
• iot-dev Layer:
  • IoT & Embedded environment: Clones and compiles Raspberry Pi openocd and picotool from source. Sets up the Pico SDK (PICO_SDK_PATH=/opt/pico-sdk). Installs cross-compilers (gcc-arm-none-eabi, gcc-riscv64-unknown-elf), debugger (gdb-multiarch), runtime dependencies, serial terminal (picocom), and python3 for build systems/scripts.

---

Project Structure

.
├── base/
│   └── Containerfile     # Debian base with Distrobox integration, ripgrep, agy, and opencode
├── c-dev/
│   └── Containerfile     # C development tools (clang, clangd, cmake, ninja-build)
├── go-dev/
│   └── Containerfile     # Go development tools (Go 1.26.5, build-essential, gopls, dlv)
├── iot-dev/
│   └── Containerfile     # IoT development tools (OpenOCD, picotool, Pico SDK, arm/riscv GCC, GDB)
├── lua-dev/
│   └── Containerfile     # Lua development tools (lua-language-server, stylua)
├── build.sh              # Sequential build automation script
└── README.md             # This file

Prerequisites

Ensure Podman and Distrobox are installed on your host system:

• Arch Linux: sudo pacman -S podman distrobox
• Fedora/RedHat: sudo dnf install podman distrobox
• Ubuntu/Debian: sudo apt install podman distrobox

How to Build

Run the build script to compile the base image first, followed by the C development image:

./build.sh

This will produce the following images:

1. localhost/debian-distrobox-base:latest
2. localhost/debian-distrobox-c:latest
3. localhost/debian-distrobox-go:latest
4. localhost/debian-distrobox-iot:latest
5. localhost/debian-distrobox-lua:latest

How to Use

1. Create a Distrobox Container

Create a new distrobox instance using the C or Go development image:

# For C/C++ development
distrobox create --image localhost/debian-distrobox-c:latest --name c-box

# For Go development
distrobox create --image localhost/debian-distrobox-go:latest --name go-box

# For Lua development
distrobox create --image localhost/debian-distrobox-lua:latest --name lua-box

# For IoT development (privileged permissions recommended for USB devices & debug probes)
distrobox create --image localhost/debian-distrobox-iot:latest --name iot-box --additional-flags "--privileged -v /dev:/dev"

2. Enter the Distrobox

Enter the created container environment:

distrobox enter c-box
# or
distrobox enter go-box

Inside the container, you have full access to your host's home directory, SSH agents, and configurations, along with:

• clang, cmake, and ninja-build (for C development) or go, gopls, and dlv (for Go development)
• git and ripgrep for source management
• nvim (Neovim) with native LSP support
• agy and opencode for terminal-based AI agent coding assistance

3. Verification

Once inside, verify that the environment is set up correctly:

For C/C++:

# Verify compilers and search
clang --version
cmake --version
ninja --version
rg --version

# Verify AI Agents
agy --version
opencode --help

For Go:

# Verify Go and tools
go version
gopls version
dlv version
rg --version

# Verify AI Agents
agy --version
opencode --help

For IoT:

# Verify compilers and debuggers
arm-none-eabi-gcc --version
riscv64-unknown-elf-gcc --version
gdb-multiarch --version
openocd --version
picotool version
picocom --version

# Verify SDK path
echo $PICO_SDK_PATH

For Lua:

# Verify interpreter and linter
luajit -v
luacheck --version

# Verify LSP and formatter
lua-language-server --version
stylua --version

Future Expansion

To add a new language layer (e.g., Python, Go, Rust), create a new directory (e.g., python/) with a Containerfile inheriting from the base:

FROM debian-distrobox-base:latest
ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y --no-install-recommends \
    python3 python3-pip python3-venv \
    && rm -rf /var/lib/apt/lists/*
CMD ["/bin/bash"]

Then, add its build command to build.sh.