mirror of
https://github.com/marcoallegretti/karapace.git
synced 2026-03-26 21:43:09 +00:00
Deterministic environment engine for immutable Linux systems
e6e0f3dd6d
Delete 14 old docs files (AI-generated, riddled with Phase/M1/1.0 jargon, references to non-existent commands, stale CI snippets). New documentation (6 files), written from repository source analysis: - docs/architecture.md — crate graph, engine lifecycle, identity computation, runtime backends, store design, WAL, GC, unsafe blocks - docs/cli-reference.md — all 23 commands with syntax, args, flags, exit codes, env vars, verified against crates/karapace-cli/src/main.rs - docs/storage-format.md — directory layout, objects, layers, metadata, manifest format, lock file, WAL, atomic write contract - docs/security-model.md — mount/device/env var policies with exact defaults from security.rs, trust assumptions, what is NOT protected - docs/build-and-reproducibility.md — CI env vars, RUSTFLAGS, cargo profile, reproducibility verification, toolchain pinning - docs/contributing.md — setup, verification, project layout, code standards, testing, CI workflows README.md rewritten: concise, no marketing language, prerequisites first, usage example, command table, limitations section. CONTRIBUTING.md now points to docs/contributing.md. CHANGELOG.md cleaned: removed M1-M8 labels, Phase refs, stale counts. |
||
|---|---|---|
| .cargo | ||
| .github | ||
| crates | ||
| data | ||
| docs | ||
| examples | ||
| scripts | ||
| .gitignore | ||
| Cargo.lock | ||
| Cargo.toml | ||
| CHANGELOG.md | ||
| CI_CONTRACT.md | ||
| CONTRIBUTING.md | ||
| deny.toml | ||
| LICENSE | ||
| README.md | ||
Karapace
Deterministic, content-addressed container environments for Linux. No root. No daemon.
Karapace builds isolated development environments from declarative TOML manifests using Linux user namespaces and overlay filesystems. Each environment gets a unique identity (blake3 hash) derived from its fully resolved dependencies.
Prerequisites
- Linux with user namespaces (
CONFIG_USER_NS=y) fuse-overlayfscurl- Optional:
crun/runc/youki(OCI backend)
Run karapace doctor to check.
Install
git clone https://github.com/marcoallegretti/karapace.git
cd karapace
cargo build --release
sudo install -Dm755 target/release/karapace /usr/local/bin/karapace
Or via cargo:
cargo install --git https://github.com/marcoallegretti/karapace.git karapace-cli
Usage
# Create a manifest
cat > karapace.toml << 'EOF'
manifest_version = 1
[base]
image = "rolling"
[system]
packages = ["git", "curl"]
[runtime]
backend = "namespace"
EOF
# Build and enter
karapace build
karapace enter <env_id>
# Run a command
karapace exec <env_id> -- git --version
# Snapshot
karapace commit <env_id>
karapace restore <env_id> <snapshot_hash>
See examples/ for more manifests: minimal.toml, dev.toml, gui-dev.toml, ubuntu-dev.toml, rust-dev.toml.
Commands
23 commands. All accept --json, --store <path>, --verbose, --trace.
build [manifest] [--name] Build environment
rebuild [manifest] [--name] Destroy + rebuild
enter <id> [-- cmd...] Enter environment
exec <id> -- <cmd...> Run command in environment
destroy <id> Destroy environment
stop <id> Stop running environment
freeze <id> Freeze (prevent writes)
archive <id> Archive (prevent entry)
list List environments
inspect <id> Show metadata
diff <id> Show overlay changes
snapshots <id> List snapshots
commit <id> Snapshot overlay
restore <id> <hash> Restore snapshot
gc [--dry-run] Garbage collect
verify-store Check store integrity
push <id> [--tag] [--remote] Push to remote
pull <ref> [--remote] Pull from remote
rename <id> <name> Rename environment
doctor Check prerequisites
migrate Check store version
completions <shell> Shell completions
man-pages [dir] Generate man pages
Workspace
9 crates:
karapace-schema Manifest, normalization, lock file, identity
karapace-store Objects, layers, metadata, WAL, GC, integrity
karapace-runtime Backends (namespace/oci/mock), images, security
karapace-core Engine: lifecycle orchestration
karapace-cli CLI (23 commands)
karapace-dbus D-Bus service (optional)
karapace-tui Terminal UI (optional)
karapace-remote Remote store client, push/pull
karapace-server Reference HTTP server
Limitations
- Linux only.
- Layer packing drops: extended attributes, device nodes, hardlinks, SELinux labels, ACLs.
- Base images are content-hashed but not GPG-verified.
- No MAC enforcement (SELinux/AppArmor) inside containers.
- Remote protocol has no authentication yet.