K8s API — without the hassle. Unleashed.

• No etcd, no control plane babysitting
• Machines are disposable; state lives with the workload
• End-to-end mTLS between machines and workloads by default
• Designed for tens of thousands of nodes, partitions, and churn

Just run, scale, enjoy!

Magik is a scale-out fabric that turns any device—cloud, on-prem, edge, or IoT—into an interchangeable compute resource. It scales out by eliminating the centralized control plane, enabling secure, self-healing workloads across highly dynamic environments.

1. Introduction
2. Why Magik
3. Core Concept
4. How Magik Compares
5. Architecture
6. Quick Start
7. Use Cases
8. Summary
9. Comparison Matrix
10. Specifications
11. Community & Support

Clouds and modern systems like Kubernetes are powerful but inherently limited by centralization. As these systems grow:

• Control planes become scaling bottlenecks.
• Consensus overhead increases.
• Infrastructure failures ripple through workloads and disrupt our digital landscape.

Magik rethinks scale-out from the ground up:

• No global consensus—fully scale-out fabric choreography.
• Consumer-aligned consistency—each application carries its own state management.
• Scale out—limited only by network capacity.

Magik starts from the assumption that everything is transient: identity, state, and trust. The system is therefore designed from the ground up for motion. Built-in self-healing, intelligent workload clustering, and mutual authentication with end-to-end encryption by design.

CAP trade-offs are expressed as A/P (Availability + Partition Tolerance) and C/P (Consistency + Partition Tolerance).

Key benefit: Machine failures do not pollute the workload. Each concern is isolated and optimized for its purpose, ensuring security, scalability, and reliability by design. This separation eliminates cross-cutting concerns and allows each plane to optimize independently. Scoping each plane to its domain prevents the monolithic anti-patterns that control-plane-centric platforms preserve.

Traditional cloud or orchestration systems stitch infrastructure to clusters and make the platform expensive and static, tying up a lot of operational resources by design.

Magik flips the model:

• Infrastructure is stateless, ephemeral, and disposable by design.
• Each stateful workload carries its own consensus (e.g., Raft for databases).

Machine failures never corrupt workloads, and the architecture enables scale-out to thousands of nodes.
Additionally, operational effort is reduced to near zero.

Magik assigns transient and separate cryptographic identities to machines and workloads, and all communication in Magik is mutually authenticated and end-to-end encrypted using mutually authenticated, encrypted streams by design:

• This separation ensures complete isolation of trust boundaries between infrastructure and workloads, implementing zero trust at the core by design.
• Machine and workload communication never share credentials.
• Even if a machine is compromised, workloads remain isolated and protected.

flowchart LR
  %% ============================================
  %% Styles
  %% ============================================
  classDef dht        fill:#EEF6FF,stroke:#4975D0,stroke-width:1px;
  classDef workload   fill:#E8FFF4,stroke:#1D7A46,stroke-width:1px;
  classDef runtime    fill:#FFF7E6,stroke:#B76B00,stroke-width:1px;
  classDef daemon     fill:#F5E6FF,stroke:#7B3FB3,stroke-width:1px;
  classDef bus        fill:#FFF0F0,stroke:#C43D3D,stroke-width:1px;
  classDef caption    fill:none,stroke-dasharray:3 3,stroke:#999,color:#666,font-size:11px;

  %% ============================================
  %% Workplane (per-workload trust domain)
  %% ============================================
  subgraph WP["Workplane (workload trust domain)"]
    direction TB

    WP_CAP["Per-workload mTLS and service discovery"]:::caption

    WDHT[(Workload DHT<br/>Service discovery)]:::dht
    W1[Workload W1]:::workload
    W2[Workload W2]:::workload

    %% Workload-to-workload mTLS
    W1 -->|mTLS| W2
    W2 -->|mTLS| W1

    %% Workload DHT for service discovery
    W1 -->|register / query| WDHT
    W2 -->|register / query| WDHT
  end

  %% ============================================
  %% Machineplane (infrastructure trust domain)
  %% ============================================
  subgraph MP["Machineplane (infrastructure trust domain)"]
    direction TB

    MP_CAP["Per-machine secure streams, node discovery, and fabric pub/sub"]:::caption

    MDHT[(Machine DHT<br/>Node discovery)]:::dht
    PS{{Pub/Sub<br/>magik-fabric topic}}:::bus

    %% ---------- Machine A ----------
    subgraph MA["Machine A"]
      direction TB
      D1[Machine Daemon A]:::daemon
      R1[(Runtime A<br/>libkrun/libcrun)]:::runtime
    end

    %% ---------- Machine B ----------
    subgraph MB["Machine B"]
      direction TB
      D2[Machine Daemon B]:::daemon
      R2[(Runtime B<br/>libkrun/libcrun)]:::runtime
    end

    %% Secure streams between daemons
    D1 -->|secure stream| D2
    D2 -->|secure stream| D1

    %% Machine DHT for node discovery
    D1 -->|announce / lookup| MDHT
    D2 -->|announce / lookup| MDHT

    %% Fabric pub/sub
    D1 -->|publish / subscribe| PS
    D2 -->|publish / subscribe| PS
  end

  %% ============================================
  %% Runtime–Workload relationship
  %% ============================================
  D1 -->|deploy / start| R1
  D2 -->|deploy / start| R2

  R1 -. hosts .-> W1
  R2 -. hosts .-> W2

The Machineplane manages infrastructure resources and scheduling, with no persistent state. It is disposable, fully decoupled, and autonomous—rebuild at will as long as you have some bootstrap source (e.g., registries, manifests, or surviving workloads) to repopulate the fabric.

The machineplane is implemented in Rust using Korium for peer-to-peer networking:

• Node discovery via Machine DHT (Kademlia).
• Decentralized workload scheduling using ephemeral tender negotiations.
• Fabric-level coordination through secure, mutually authenticated streams.
• Resource offering and bidding, capability advertisement, and local policy enforcement.
• Workload isolation via microVM (KrunEngine/libkrun, default) or container (CrunEngine/libcrun for IoT/edge).
• First-class WebAssembly support via CrunEngine (wasmedge/wasmtime OCI handlers).
• Lifecycle hooks to start and stop workloads via the runtime.

Operational impact: no etcd, no API servers, no manager quorum, no backups—near-zero operational toll.

Traditional schedulers maintain global fabric state and enforce consensus (Raft, etcd), creating bottlenecks. Magik uses ephemeral scheduling: tenders are never persisted, and scheduling happens dynamically across the scale-out fabric.

• Each machine verifies scheduling message authenticity using Ed25519 signatures.
• All communications are encrypted and mutually authenticated using QUIC transport with TLS 1.3.
• Replay protection via (timestamp, nonce) tuples with ±30 second clock skew tolerance.
• Rogue nodes cannot influence scheduling without a valid cryptographic identity.

The Workplane runs as the infra container in every Pod (replacing the standard pause container), providing per-workload service discovery and self-healing.

• Each Pod uses a unique Workload Peer ID (Ed25519).
• Secure communication is independent of machine identities (separate trust domains).
• Prevents cross-plane privilege escalation.

• Rust 1.85+ (rustup update stable) — Edition 2024 required
• Runtime Libraries (for actual workload execution):
  • Linux: libkrun 1.10+ (microVM via KVM) and/or libcrun 1.8+ (container for IoT)
  • macOS: libkrun 1.16+ and libkrunfw 4.10+ (microVM via HVF)

Note: The codebase compiles on all platforms. Runtime engines use stubs on unsupported platforms, returning "unavailable" at runtime. This enables unified development and CI across Linux, macOS, and other systems.

# Install libkrun and libkrunfw (uses Apple Hypervisor Framework)
brew tap slp/krun
brew install slp/krun/libkrun slp/krun/libkrunfw

# Install LLVM (required for build-time FFI generation)
brew install llvm

# Create libkrunfw version symlink (libkrun expects v5, brew installs v4)
sudo ln -sf /opt/homebrew/lib/libkrunfw.4.dylib /opt/homebrew/lib/libkrunfw.5.dylib

# Set environment for build
export LIBCLANG_PATH=/opt/homebrew/opt/llvm/lib
export LIBRARY_PATH=/opt/homebrew/lib:$LIBRARY_PATH
export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH

macOS requires the com.apple.security.hypervisor entitlement for HVF access. Binaries must be signed with this entitlement to create VMs:

# Sign the machineplane binary
codesign --force --sign - --entitlements machineplane/entitlements.plist target/release/machineplane

# For tests: find and sign the test binary (exclude .d metadata files)
TEST_BIN=$(find target/release/deps -name 'apply_tests-*' -type f ! -name '*.d')
codesign --force --sign - --entitlements machineplane/entitlements.plist "$TEST_BIN"

# Run tests with VM support
MAGIK_FORCE_VM_TESTS=1 DYLD_LIBRARY_PATH=/opt/homebrew/lib "$TEST_BIN" <test_name> --nocapture

For development: After each build, re-sign the binary before running. The entitlements.plist file is included in the repository.

# Clone the repository
git clone https://github.com/magik/magik.git
cd magik

# Build all components (development)
cargo build --release

For production deployments, the workplane binary must be statically linked and embedded into machineplane:

# Install musl target for static linking
rustup target add x86_64-unknown-linux-musl

# On macOS: install musl cross-compiler
brew install FiloSottile/musl-cross/musl-cross

# Build workplane as static binary for containers
cargo build -p workplane --release --target x86_64-unknown-linux-musl

# Rebuild machineplane (automatically embeds workplane via build.rs)
cargo build -p machineplane --release

This creates a self-contained machineplane that:

• Extracts the embedded workplane binary at startup
• Creates a minimal OCI image (localhost/magik/workplane:latest)
• Uses it as the infra container for all pods (replacing pause)

# Start a single node (uses libkrun by default)
./target/release/machineplane

# Start with explicit configuration
./target/release/machineplane \
  --rest-api-port 3000 \
  --korium-port 4001 \
  --bootstrap-peer "<identity_hex>@<ip:port>"

The workplane agent runs automatically as the infra container in every pod deployed by machineplane. No manual invocation is required.

When machineplane deploys a manifest, it:

1. Uses localhost/magik/workplane:latest as the pod's infra container
2. Passes workload identity via command-line arguments
3. The agent provides mesh networking, service discovery, and self-healing

For manual testing or development, you can run the workplane binary directly:

./target/release/workplane \
  --namespace default \
  --workload nginx \
  --pod nginx-0 \
  --workload-kind Deployment \
  --replicas 3 \
  --liveness-url http://127.0.0.1:8080/health \
  --readiness-url http://127.0.0.1:8080/ready \
  --privkey $BEE_PRIVATE_KEY_B64

# Create a deployment
curl -X POST http://localhost:3000/apis/apps/v1/namespaces/default/deployments \
  -H "Content-Type: application/yaml" \
  -d @nginx-deployment.yaml

# List deployments
curl http://localhost:3000/apis/apps/v1/namespaces/default/deployments

# List pods
curl http://localhost:3000/api/v1/namespaces/default/pods

# Delete a deployment
curl -X DELETE http://localhost:3000/apis/apps/v1/namespaces/default/deployments/nginx

Magik represents a paradigm shift in orchestration:

• Eliminates centralized control planes and scaling bottlenecks.
• Uses ephemeral, decentralized scheduling for effectively unparalleled scalability.
• Provides strict isolation between infrastructure and workloads.
• Ensures all communications are mutually authenticated and encrypted.
• Scales to tens of thousands of nodes, ideal for edge, IoT, cloud, multicloud, and air-gapped environments.
• A disposable, fully decoupled Machineplane enables autonomous, low-toil operations.

Magik is not just another orchestration system—it is a secure, scale-out choreography fabric for the future of global computing.

Note on "Mutually Authenticated Streams": legacy systems may add this via optional plugins or sidecars, but it is not default fabric behavior.

For full normative details, see:

• Technical Specification: technical-spec.md
  Comprehensive technical details including data structures, wire protocols, and API reference.

• Machineplane Spec: machineplane/machineplane-spec.md
  Node discovery, ephemeral scheduling, deployment, security, failure handling, and observability.

• Workplane Spec: workplane/workplane-spec.md
  Per-workload service discovery, workload identity, secure workload-to-workload connectivity, self-healing, and consistency gating.

• GitHub: github.com/magik/magik
• Documentation: docs.magik.io
• License: Apache 2.0