Karapace

A deterministic container environment engine for immutable Linux systems.

Karapace creates isolated, reproducible development environments using Linux namespaces and overlay filesystems — no root, no daemon, no Docker. Environments are content-addressed artifacts derived from declarative TOML manifests, with full host integration for GPU, audio, Wayland, and desktop applications.

What Karapace Is (and Isn't)

Karapace is the identity and certainty layer for reproducible environments. It is not a general-purpose container runtime.

Need	Tool
Full system container lifecycle, advanced networking, snapshots	Incus, LXD, Podman
Deterministic, content-addressed, reproducible environments	Karapace
Quick disposable containers with zero config	Distrobox
Determinism + simplicity for casual use	Karapace quick command

Karapace is complementary — it can sit on top of or alongside any container runtime. Users needing full container features use a runtime; users needing reproducibility and traceability use Karapace. The quick command bridges the gap for users who want both simplicity and determinism.

Features

• Real container isolation — Linux user namespaces (unshare), fuse-overlayfs, chroot
• No root required — runs entirely as an unprivileged user
• No daemon — direct CLI, no background service needed
• Multi-distro images — openSUSE, Ubuntu, Debian, Fedora, Arch from LXC image servers
• Package installation — zypper, apt, dnf, pacman inside the container
• Host integration — home directory, Wayland, PipeWire, D-Bus, GPU (/dev/dri), audio (/dev/snd), SSH agent, fonts, themes
• Desktop app export — export GUI apps as .desktop files on the host
• OCI runtime support — optional crun/runc/youki backend
• Content-addressable store — deterministic hashing, deduplication, integrity verification
• Overlay drift control — diff, freeze, commit, export writable layer changes
• OSC 777 terminal markers — container-aware terminal integration (Konsole, etc.)

Crate Layout

Crate	Purpose
karapace-schema	Manifest v1 parsing, normalization, identity hashing, lock file
karapace-store	Content-addressable store, layers, metadata, GC, integrity
karapace-runtime	Container runtime: image download, sandbox, host integration, app export
karapace-core	Build engine, lifecycle state machine, drift control, concurrency
karapace-cli	Full CLI interface (23 commands)
karapace-dbus	Socket-activated D-Bus desktop integration (optional, feature-gated)
karapace-remote	Remote content-addressable store, push/pull, registry
karapace-server	Reference remote server implementing protocol v1 (tiny_http)
karapace-tui	Terminal UI for environment management (ratatui)

CLI Commands (23)

karapace build [manifest]                   # Build environment from manifest
karapace rebuild [manifest]                 # Destroy + rebuild
karapace enter <env_id> [-- cmd...]         # Enter environment (or run a command)
karapace exec <env_id> -- <cmd...>          # Execute command inside environment
karapace destroy <env_id>                   # Destroy environment
karapace stop <env_id>                      # Stop a running environment
karapace freeze <env_id>                    # Freeze environment
karapace archive <env_id>                   # Archive environment (preserve, prevent entry)
karapace list                               # List all environments
karapace inspect <env_id>                   # Show environment metadata
karapace diff <env_id>                      # Show overlay drift
karapace snapshots <env_id>                 # List snapshots for an environment
karapace commit <env_id>                    # Commit overlay drift as snapshot
karapace restore <env_id> <snapshot>        # Restore overlay from snapshot
karapace gc [--dry-run]                     # Garbage collect store
karapace verify-store                       # Check store integrity
karapace push <env_id> [--tag name@tag]     # Push environment to remote store
karapace pull <reference> [--remote url]    # Pull environment from remote store
karapace rename <env_id> <name>             # Rename environment
karapace doctor                             # Run diagnostic checks on system and store
karapace migrate                            # Check store version and migration guidance
karapace completions <shell>                # Generate shell completions
karapace man-pages [dir]                    # Generate man pages

All commands support --json for structured output, --store <path> for custom store location, --verbose / -v for debug logging, and --trace for trace-level output.

Set KARAPACE_LOG=debug (or info, warn, error, trace) for fine-grained log control.

Quick Start

# Build (core CLI only — D-Bus service is opt-in)
cargo build --release

# Build with D-Bus desktop integration
cargo build --release --workspace

# Write a manifest
cat > karapace.toml << 'EOF'
manifest_version = 1

[base]
image = "rolling"    # openSUSE Tumbleweed (or "ubuntu/24.04", "fedora/41", "arch", etc.)

[system]
packages = ["git", "curl", "vim"]

[hardware]
gpu = true
audio = true

[runtime]
backend = "namespace"
EOF

karapace build
karapace enter <env_id>

# Run a command inside without interactive shell
karapace exec <env_id> -- git --version

# Snapshot and restore
karapace commit <env_id>
karapace snapshots <env_id>
karapace restore <env_id> <snapshot_hash>

# Push/pull to remote
karapace push <env_id> --tag my-env@latest
karapace pull my-env@latest

# List environments
karapace list

Example Manifests

Ready-to-use manifests in examples/:

File	Description
examples/minimal.toml	Bare openSUSE system, no extras
examples/dev.toml	Developer tools (git, vim, tmux, gcc, clang)
examples/gui-dev.toml	GUI development with GPU + audio passthrough
examples/ubuntu-dev.toml	Ubuntu-based with Node.js, Python, build-essential
examples/rust-dev.toml	Rust development environment

Shell Completions

# Bash
karapace completions bash > /etc/bash_completion.d/karapace

# Zsh
karapace completions zsh > /usr/share/zsh/site-functions/_karapace

# Fish
karapace completions fish > ~/.config/fish/completions/karapace.fish

Man Pages

karapace man-pages /usr/share/man/man1

Installation

From Source (recommended)

git clone https://github.com/marcoallegretti/karapace.git
cd karapace
cargo build --release
sudo install -Dm755 target/release/karapace /usr/local/bin/karapace

With D-Bus Service

cargo build --release --workspace
sudo install -Dm755 target/release/karapace /usr/local/bin/karapace
sudo install -Dm755 target/release/karapace-dbus /usr/local/bin/karapace-dbus
sudo install -Dm644 data/dbus/org.karapace.Manager1.service /usr/share/dbus-1/services/
sudo install -Dm644 data/systemd/karapace-dbus.service /usr/lib/systemd/user/

Via Cargo

cargo install --git https://github.com/marcoallegretti/karapace.git karapace-cli

Prerequisites

• Linux with user namespace support (CONFIG_USER_NS=y)
• fuse-overlayfs (for overlay filesystem)
• curl (for image downloads)
• Optional: crun/runc/youki (for OCI backend)

Karapace checks for missing prerequisites at startup and provides distro-specific install instructions.

Documentation

• Getting Started Guide — installation, first use, common workflows
• Architecture Overview
• Manifest v1 Specification
• Lock File v2 Specification
• Store Format v2 Specification
• Hash Contract
• Security Model
• CLI Stability Contract
• Remote Protocol v1 (Draft)
• Layer Limitations (Phase 1)
• Public API Reference
• Versioning Policy
• Verification & Supply Chain
• E2E Testing

Verification

cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo build --release --workspace