magikrun

OCI-Compliant Container Runtime Abstraction Layer

magikrun provides a pure OCI Runtime Spec compliant interface for container operations across heterogeneous isolation backends. It handles single-container operations only—pod semantics (shared namespaces, pause containers) are delegated to the higher-level magikpod crate.

Runtime Flavours Matrix

At a Glance

Platform Detection

magikrun automatically detects available capabilities at runtime:

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                           magikrun                                  │
├─────────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │                    OciRuntime Trait                         │    │
│  │    create(id, bundle) → start(id) → kill(id) → delete(id)  │    │
│  │                         state(id)                           │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                              │                                      │
│  ┌───────────────────────────┼───────────────────────────────┐      │
│  │                   Bundle Building                         │      │
│  │  OCI Image → Layers → Rootfs + config.json                │      │
│  │  Path traversal protection │ Size limits │ Whiteout files │      │
│  └───────────────────────────┼───────────────────────────────┘      │
│                              │                                      │
│  ┌───────────────────────────┼───────────────────────────────┐      │
│  │               Content-Addressed Storage                   │      │
│  │  Digest verification │ Deduplication │ Atomic writes      │      │
│  └───────────────────────────────────────────────────────────┘      │
├─────────────────────────────────────────────────────────────────────┤
│                      Runtime Backends                               │
│  ┌──────────────────┐  ┌───────────────────┐  ┌───────────────┐     │
│  │  NativeRuntime    │  │  WindowsRuntime   │  │WasmtimeRuntime│     │
│  │     (Linux)      │  │    (Windows)      │  │  (Cross-plat) │     │
│  │   Namespaces     │  │  WSL2 + Jobs      │  │  WASI + Fuel  │     │
│  │   Cgroups v2     │  │  Linux on Win     │  │  256MB limit  │     │
│  └──────────────────┘  └───────────────────┘  └───────────────┘     │
│                                                                     │
│  ┌──────────────────┐                                               │
│  │   KrunRuntime    │                                               │
│  │    (MicroVM)     │                                               │
│  │   KVM / HVF      │                                               │
│  │    4GB limit     │                                               │
│  └──────────────────┘                                               │
└─────────────────────────────────────────────────────────────────────┘

OCI Runtime Spec Compliance

Implements the OCI Runtime Spec container lifecycle:

                   ┌──────────────────────────────────────────────┐
                   │                                              │
                   ▼                                              │
  ┌─────────┐   create   ┌─────────┐   start   ┌─────────┐       │
  │ (none)  │ ─────────► │ Created │ ────────► │ Running │       │
  └─────────┘            └─────────┘           └────┬────┘       │
                              │                     │            │
                              │ delete              │ kill       │
                              │ (if created)        │            │
                              ▼                     ▼            │
                         ┌─────────┐           ┌─────────┐       │
                         │ Deleted │ ◄──────── │ Stopped │ ──────┘
                         └─────────┘  delete   └─────────┘

Core Operations

Runtime Backends

Isolation Hierarchy

Defense-in-depth with layered isolation:

┌───────────────────────────────────────────────────┐
│                  KrunRuntime                      │  ← Hardware VM boundary
│  ┌─────────────────────────────────────────────┐  │
│  │       NativeRuntime / WindowsRuntime         │  │  ← Kernel/OS boundary
│  │  ┌───────────────────────────────────────┐  │  │
│  │  │         WasmtimeRuntime               │  │  │  ← WASM sandbox boundary
│  │  │                                       │  │  │
│  │  └───────────────────────────────────────┘  │  │
│  └─────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────┘

Security Model

Key Security Properties

• Path Traversal Protection: All tar extraction validates paths against .. components and absolute paths
• Size Limits: Bounded constants prevent resource exhaustion
• Digest Verification: Content-addressed storage verifies SHA-256 before storing blobs
• Fuel Limits: WASM execution bounded by instruction count
• Timeouts: All network operations bounded

Security Constants

Usage

Add Dependency

[dependencies]
magikrun = "0.1"

Example

use magikrun::{Platform, BlobStore, pull_image, BundleBuilder};
use magikrun::runtimes::RuntimeRegistry;

#[tokio::main]
async fn main() -> magikrun::Result<()> {
    // Detect platform and available runtimes
    let platform = Platform::detect();
    let registry = RuntimeRegistry::new(&platform)?;
    
    // List available runtimes
    for name in registry.available_runtimes() {
        println!("Available: {}", name);
    }

    // Pull image and store layers
    let storage = std::sync::Arc::new(BlobStore::new()?);
    let image = pull_image("alpine:3.18", &storage).await?;
    
    // Build OCI bundle
    let builder = BundleBuilder::new()?;
    let bundle = builder
        .image(&image)
        .storage(&storage)
        .build()
        .await?;
    
    // Get a runtime and run container
    if let Some(runtime) = registry.get("wasmtime") {
        runtime.create("my-container", &bundle).await?;
        runtime.start("my-container").await?;
        
        // Check state
        let state = runtime.state("my-container").await?;
        println!("Status: {:?}", state.status);
        
        // Cleanup
        runtime.kill("my-container", magikrun::Signal::Term).await?;
        runtime.delete("my-container").await?;
    }
    
    Ok(())
}

No Pod Semantics

This crate intentionally excludes pod-level concepts. Each container is independent. For namespace sharing and pod orchestration, use magikpod which configures namespace paths in config.json:

{
  "linux": {
    "namespaces": [
      { "type": "pid" },
      { "type": "network", "path": "/proc/1234/ns/net" }
    ]
  }
}

Bundle Formats

Platform Detection

use magikrun::{Platform, Capability};

let platform = Platform::detect();

// Check OS and architecture
println!("OS: {}, Arch: {}", platform.os, platform.arch);

// Check available capabilities
if platform.has_capability(Capability::Namespaces) {
    println!("Linux containers available");
}

if platform.has_capability(Capability::Hypervisor) {
    println!("MicroVM isolation available");
}

// WASM is always available
assert!(platform.has_capability(Capability::WasmRuntime));

Content-Addressed Storage

The BlobStore provides secure, deduplicated storage for OCI layers:

use magikrun::BlobStore;
use sha2::{Sha256, Digest};

let store = BlobStore::new()?;

// Store with automatic verification
let data = b"layer content";
let digest = format!("sha256:{}", hex::encode(Sha256::digest(data)));
store.put_blob(&digest, data)?;

// Retrieve
let retrieved = store.get_blob(&digest)?;
assert_eq!(retrieved, data);

// Deduplication: same content = same digest = one copy on disk

Storage Layout

~/.magikrun/blobs/
└── sha256/
    ├── ab/
    │   ├── abcd1234...  (blob content)
    │   └── ab9f8e7d...  (blob content)
    └── cd/
        └── cdef5678...  (blob content)

Testing

# Run all tests
cargo test

# Run with verbose output
cargo test -- --nocapture

# Run specific test file
cargo test --test storage_tests

Test Coverage

• 130 tests covering:
  • Security-critical constants validation
  • Error message formatting
  • Platform detection logic
  • Container state serialization (OCI spec compliance)
  • Runtime registry and availability
  • Blob storage operations

Dependencies

Core

• tokio - Async runtime
• async-trait - Async trait definitions
• serde / serde_json - Serialization

OCI

• oci-spec - OCI image manifest types
• oci-distribution - Registry client

Runtimes

• wasmtime / wasmtime-wasi - WASM execution (v27)
• krun-sys - libkrun FFI bindings (v1.10)
• libcontainer / libcgroups - youki runtime (Linux, cgroups v2)

Security

• sha2 / hex - Content-addressed hashing
• flate2 / tar - Layer extraction with bounds checking

License

Apache-2.0. See LICENSE for details.

This project uses runtime backends (youki, wasmtime, libkrun) and OCI libraries that are also Apache-2.0 licensed.

Related Projects

• magikpod - Pod-level orchestration with namespace sharing
• magik - Decentralized workload orchestration
• korium - P2P mesh networking