ArchBox - Multi-Architecture Linux Container Manager

ArchBox is a lightweight container management tool that simplifies the process of creating and managing Linux containers for different architectures. It provides a unified interface for working with various Linux distributions across multiple CPU architectures.

Features

• Multi-distribution support - Ubuntu, Debian, and more
• Multi-architecture support - amd64, arm64, armhf, ppc64le, s390x, riscv64
• Container management - Create, list, remove containers
• State tracking - Persistent container state management
• JSON configuration - Easy to extend with new distributions
• Lightweight - Minimal dependencies and fast operation

Supported Distributions

Ubuntu

• noble (24.04 LTS)
• jammy (22.04 LTS)
• focal (20.04 LTS)

Debian

• bookworm (12)
• bullseye (11)

Supported Architectures

• amd64 - Intel x86 64-bit
• arm64 - ARM 64-bit (mapped to arm64v8)
• armhf - ARM 32-bit hard float (mapped to arm32v7)
• ppc64le - PowerPC 64-bit little-endian
• s390x - IBM System/390 64-bit
• riscv64 - RISC-V 64-bit

Prerequisites

• Docker installed and running
• GCC compiler (for building archbox itself)
• Make (optional, for using the Makefile)

Building

Using Make (recommended)

make

Manual compilation

gcc -Wall -Wextra -O2 -std=c11 -o archbox archbox.c json.c

Installation

System-wide installation

sudo ./install.sh

This installs to /opt/archbox/ with a symlink in /usr/local/bin/.

Local use

Simply place the archbox binary in your project root directory or add it to your PATH.

Usage

Basic Syntax

archbox <command> [options]

Commands

List available distributions and architectures

archbox list

Create a new container

# Create Ubuntu 24.04 for amd64
archbox create ubuntu noble amd64

# Create Debian 12 for arm64
archbox create debian bookworm arm64

# Create with custom name
archbox create ubuntu noble amd64 mycontainer

List running containers

archbox ps

Execute commands in container

# Run interactive shell
archbox exec mycontainer

# Run specific command
archbox exec mycontainer ls -la /root

Stop and remove containers

# Stop container
archbox stop mycontainer

# Remove container
archbox rm mycontainer

# Stop and remove
archbox stop mycontainer && archbox rm mycontainer

Container state management

# Show container state
archbox state mycontainer

# Reset container state
archbox reset mycontainer

Configuration

ArchBox uses distros.json for distribution and architecture configuration. The file is searched in the following order:

1. Next to the archbox binary
2. /usr/local/share/archbox/distros.json
3. /usr/share/archbox/distros.json

Adding new distributions

Edit distros.json to add new distributions:

{
  "newdistro": {
    "versions": {
      "version1": {
        "architectures": ["amd64", "arm64"]
      }
    },
    "arch_map": {
      "amd64": "amd64",
      "arm64": "arm64v8"
    }
  }
}

How It Works

1. Configuration Loading: ArchBox loads distribution data from distros.json
2. Architecture Mapping: Maps user-friendly architecture names to Docker platform names
3. Container Management: Uses Docker API to create and manage containers
4. State Tracking: Maintains persistent state in ~/.archbox/
5. Command Execution: Provides interface for container interaction

Examples

Complete Workflow

# 1. Install archbox
sudo ./install.sh

# 2. List available options
archbox list

# 3. Create container for development
archbox create ubuntu noble amd64 dev-env

# 4. Work in container
archbox exec dev-env

# 5. Clean up when done
archbox rm dev-env

Multi-Architecture Development

# Create containers for different architectures
archbox create ubuntu noble amd64 ubuntu-amd64
archbox create ubuntu noble arm64 ubuntu-arm64
archbox create debian bookworm s390x debian-s390x

# Test across architectures
archbox exec ubuntu-amd64 uname -m
archbox exec ubuntu-arm64 uname -m
archbox exec debian-s390x uname -m

Troubleshooting

Docker not running

Ensure Docker is installed and running:

docker --version
docker info

Permission denied

If you get permission errors, you may need to run Docker commands with sudo or add your user to the docker group:

sudo usermod -aG docker $USER

Configuration not found

If distros.json is not found, check:

# Find where archbox is installed
which archbox

# Check for distros.json in expected locations
ls -la /usr/local/share/archbox/
ls -la /usr/share/archbox/

Container creation fails

Ensure the requested distribution and architecture combination is supported:

archbox list

Cleaning

Remove built files:

make clean

Uninstall system installation:

sudo make uninstall
# Or if using install script:
sudo /opt/archbox/uninstall.sh