karapace/docs/architecture.md

Architecture

Workspace

Karapace is a Cargo workspace of 9 crates.

karapace-schema     Manifest parsing, normalization, lock file, identity hashing
karapace-store      Content-addressable object store, layers, metadata, WAL, GC
karapace-runtime    Container backends, image cache, security policy, prerequisites
karapace-core       Engine: orchestrates the full environment lifecycle
karapace-cli        CLI binary (23 commands, clap)
karapace-dbus       D-Bus service (org.karapace.Manager1, zbus)
karapace-tui        Terminal UI (ratatui, crossterm)
karapace-remote     Remote store client: HTTP backend, registry, push/pull
karapace-server     Reference HTTP server for remote store (tiny_http)

Dependency graph

karapace-cli ──┬──> karapace-core ──┬──> karapace-schema
               │                    ├──> karapace-store
               │                    ├──> karapace-runtime
               │                    └──> karapace-remote
               ├──> karapace-runtime
               └──> karapace-store

karapace-dbus ────> karapace-core
karapace-tui ─────> karapace-core
karapace-remote ──> karapace-store
karapace-server ──> karapace-remote, karapace-store

Engine lifecycle

karapace-core::Engine is the central orchestrator. All state transitions go through it.

                  ┌─────────┐
   build()  ───> │ Defined  │
                  └────┬────┘
                       │ resolve → lock → build
                       v
                  ┌─────────┐
                  │  Built   │ <── rebuild()
                  └──┬──┬───┘
          enter() │  │  │ freeze()
                  v  │  v
           ┌─────────┐  ┌─────────┐
           │ Running  │  │ Frozen  │
           └─────────┘  └────┬────┘
                              │ archive()
                              v
                        ┌──────────┐
                        │ Archived │
                        └──────────┘

State transitions are validated in karapace-core/src/lifecycle.rs. Invalid transitions return CoreError.

Build pipeline

Engine::build(manifest_path) executes:

1. Parse manifest (karapace-schema::parse_manifest_file)
2. Normalize (ManifestV1::normalize) — sort packages, deduplicate, lowercase backend
3. Select runtime backend (karapace-runtime::select_backend)
4. Resolve — backend downloads base image, computes content digest, queries package manager for exact versions → ResolutionResult
5. Create lock file (LockFile::from_resolved) with pinned versions and content digest
6. Compute identity (LockFile::compute_identity) → env_id (blake3)
7. Store manifest as object, create layers, write metadata
8. Backend builds the environment filesystem
9. Write lock file to disk

Identity computation

Defined in karapace-schema/src/lock.rs::LockFile::compute_identity().

Input fed to blake3 in order:

• base_digest:<content_hash>
• pkg:<name>@<version> for each resolved package (sorted)
• app:<name> for each app (sorted)
• hw:gpu / hw:audio if enabled
• mount:<label>:<host>:<container> for each mount (sorted)
• backend:<name>
• net:isolated if enabled
• cpu:<value> / mem:<value> if set

Output: 64-character hex blake3 digest. First 12 characters = short_id.

Container runtime

karapace-runtime/src/backend.rs defines RuntimeBackend trait:

pub trait RuntimeBackend: Send + Sync {
    fn name(&self) -> &str;
    fn available(&self) -> bool;
    fn resolve(&self, spec: &RuntimeSpec) -> Result<ResolutionResult, RuntimeError>;
    fn build(&self, spec: &RuntimeSpec) -> Result<(), RuntimeError>;
    fn enter(&self, spec: &RuntimeSpec) -> Result<(), RuntimeError>;
    fn exec(&self, spec: &RuntimeSpec, command: &[String]) -> Result<Output, RuntimeError>;
    fn destroy(&self, spec: &RuntimeSpec) -> Result<(), RuntimeError>;
    fn status(&self, env_id: &str) -> Result<RuntimeStatus, RuntimeError>;
}

Three backends (karapace-runtime/src/backend.rs::select_backend):

Backend	Implementation	Use
namespace	unshare + fuse-overlayfs + chroot	Default. Unprivileged.
oci	crun / runc / youki	OCI-compatible runtimes.
mock	Deterministic stubs	Testing only.

Image cache

karapace-runtime/src/image.rs::ImageCache stores downloaded base images under <store_root>/images/<cache_key>/rootfs/.

Images are fetched from images.linuxcontainers.org. The content digest is a blake3 hash of the rootfs directory tree (compute_image_digest). Package manager is auto-detected from rootfs contents (detect_package_manager).

Content-addressable store

All persistent data lives under <store_root>/store/. See storage-format.md for the full layout.

• Objects: keyed by blake3 hash of content. Written atomically (tempfile + rename). Verified on every read.
• Layers: JSON manifests describing tar archives. Kinds: Base, Dependency, Policy, Snapshot.
• Metadata: JSON per environment. Includes state, layers, ref count, checksum.

Snapshot mechanism

Engine::commit(env_id):

1. Pack the overlay upper directory into a deterministic tar (pack_layer)
2. Store tar as object
3. Create a Snapshot layer manifest with composite hash: blake3("snapshot:{env_id}:{base_layer}:{tar_hash}")

Engine::restore(env_id, snapshot_hash):

1. Retrieve snapshot layer and its tar object
2. Unpack to store/staging/restore-{env_id}
3. Atomic rename-swap with the environment's upper directory

Deterministic packing: entries sorted, timestamps zeroed, owner 0:0, permissions preserved. Symlinks preserved. Extended attributes, device nodes, hardlinks, ACLs, SELinux labels are dropped.

Garbage collection

Engine::gc(store_lock, dry_run) in karapace-core/src/engine.rs. Caller must hold StoreLock.

Protected from collection:

• Environments with state Running or Archived
• Layers referenced by any live environment
• Snapshot layers whose parent is a live base layer
• Objects referenced by any live layer or live metadata manifest_hash

Everything else is orphaned and removed. GC supports SIGINT/SIGTERM cancellation.

Write-ahead log

karapace-store/src/wal.rs. JSON entries in store/wal/.

Operations tracked: Build, Rebuild, Commit, Restore, Destroy, Gc.

Each entry records rollback steps (RemoveDir, RemoveFile). On Engine::new(), incomplete WAL entries are replayed in reverse order, then deleted. Corrupt entries are silently removed.

Concurrency

karapace-core/src/concurrency.rs::StoreLock uses flock(2) on store/.lock. All mutating CLI commands and D-Bus methods acquire this lock.

Signal handling

karapace-core/src/concurrency.rs::install_signal_handler() registers SIGINT/SIGTERM via ctrlc crate. Sets an atomic flag checked by GC and long-running operations.

Unsafe code

Five unsafe blocks in the codebase:

Location	Call	Purpose
karapace-core/src/engine.rs:455	libc::kill(SIGTERM)	Stop running environment
karapace-core/src/engine.rs:475	libc::kill(SIGKILL)	Force-kill after timeout
karapace-runtime/src/sandbox.rs:46	libc::getuid()	Get current UID for namespace setup
karapace-runtime/src/sandbox.rs:53	libc::getgid()	Get current GID for namespace setup
karapace-runtime/src/terminal.rs:41	libc::isatty()	Detect terminal for interactive mode