Royak — a swarm of containers, one tiny binary

How it works

One loop. Desired state in, real containers out.

Every few seconds Royak reads what you asked for, reads what Docker is actually running, diffs the two, and acts. That’s the whole trick — the same reconcile model Kubernetes implements with etcd, kubelet, kube-proxy and a control plane, collapsed into one process.

Read desired state

Your YAML specs — Deployments, Services, ConfigMaps, 22+ resource kinds — parsed and held as the target world.

Read actual state

Live queries against the Docker API. No cache to go stale: what Docker says is what counts.

Diff & act

Missing pod? Create it. Crashed? Restart it — with CrashLoopBackOff so it never spins forever. Too many? Remove.

royak — 2 minutes from clone to cluster

$ royak apply examples/nginx.yaml
  ✓ deployment/web applied
  [scale] web: 0 → 2 (+2)
    [mtls] rk-web-1 cert issued (CA: 1e7788c2…, expires: 90d)
    [create] rk-web-1 (main) → e30a2a93a6ce
    [start] rk-web-1 ✓
    [start] rk-web-2 ✓

$ royak get pods
  NAME       IMAGE          STATE     STATUS
  rk-web-2   nginx:alpine   running   Up Less than a second
  rk-web-1   nginx:alpine   running   Up Less than a second
  2 pod(s) total

$ royak scale web 5
  Scaling web: 2 → 5
    [start] rk-web-3 ✓  [start] rk-web-4 ✓  [start] rk-web-5 ✓

$ royak api &
$ kubectl --server=http://localhost:6443 get pods
NAME       AGE
rk-web-5   0s
rk-web-4   0s
…your existing kubectl, no --validate=false.

Features

Small binary. Not a small feature set.

Everything below is exercised by the test suite on every commit — 85 unit tests plus 120+ integration checks across six suites, and a feature-by-feature compatibility ledger verified against a real kubectl.

📦Deployments & StatefulSets

Create, scale, delete with CPU/memory limits and HPA autoscaling. StatefulSets get ordered startup, stable identity and per-ordinal volumes.

🔄Rolling updates & rollback

Zero-downtime rollouts with readiness checks and auto-rollback on timeout. Rollback works even after the rollout completes.

🌐Services & ingress

ClusterIP discovery with pod-to-service DNS, NodePort via the built-in ServiceLB (userspace load balancer), and a live ingress reverse proxy — async, streaming, TLS.

🔐RBAC & secrets

Role-based access enforced on every API write. Secrets encrypted at rest with AES-256-GCM. mTLS cluster CA with per-pod certificates.

🤝kubectl compatible

get, describe, delete, watch, logs, scale, exec -it, get events and apply with client-side updates.

🖧Multi-node mesh

UDP autodiscovery, pod distribution, heartbeat monitoring, and a cross-node service proxy so pods on node B reach services on node A.

⚙️Operators & custom resources

Define an Operator plus a CustomResource in YAML and Royak auto-provisions and manages the lifecycle.

🛡️Guards

Declarative auto-remediation: pod crash → restart, high memory → scale up. Anomaly detection watches cluster telemetry.

🚀Pipelines & jobs

CI/CD pipelines with DAG dependencies, git triggers and matrix builds. Jobs, CronJobs, Functions — all as YAML kinds.

📊Dashboard & metrics

Built-in web dashboard and a Prometheus /metrics endpoint. Log aggregation with search.

🧠Neural brain (experimental)

A small neural net trains on cluster telemetry for anomaly detection and load prediction. It monitors — the reconcile loop decides.

🤖MCP server

13 tools for AI-assistant integration: deploy, scale, exec, logs, top — manage the swarm in natural language.

Beta status

Beta means beta. Here’s the honest ledger.

Royak is an MVP of a vision — great for learning, demos, homelabs and edge boxes. It is not ready to carry your production. We test every feature in CI, but our testing is not a substitute for yours: evaluate it against your own workloads, and use it at your own risk (MIT, as-is, no warranty). Every gap below is designed and scheduled in the public roadmap, not swept under a rug. The full feature-by-feature ledger — every row verified live against a real kubectl — lives in COMPATIBILITY.md.

solidSingle nodeDeploy, scale, rolling update, rollback, probes, CrashLoopBackOff — covered by the test suite end to end.

solidkubectl workflowget / describe / delete / watch / logs / scale / exec / events, apply with client-side updates — verified against kubectl v1.36.

solidNodePort ServiceLBUserspace load balancer binds every nodePort and round-robins across pods — works on macOS and Linux.

partialMulti-nodeControl-plane sync, mesh proxy and HA leader-lease failover work and are tested — but not battle-tested at scale. Split-brain across independent disks is possible until Raft lands.

partialRaft consensusopenraft is integrated: leader election and log replication are proven in tests (in-process + HTTP transports). The live write path doesn’t go through Raft yet — that’s the next milestone.

partialCanary releasesParsed and scheduled with weighted steps; service-layer traffic splitting still needs its proxy integration.

not yetHelm engineNo native chart rendering. helm template ./chart | royak apply - works today.

solidexec & port-forwardkubectl exec including -it (TTY, resize) works over WebSocket; royak port-forward tunnels local→pod. kubectl port-forward's SPDY tunnel is the one remaining caveat.

experimentalNeuroPod runtimeDocker-free OCI runtime with its own isolation. Works on Linux with root; macOS path is not end-to-end. Clearly flagged, off by default.

Install

Clone to cluster in about two minutes.

Build from source, or grab a pre-built beta binary for Linux (x86_64/aarch64) and macOS (Apple silicon/Intel) from GitHub Releases.

Build & run

# prerequisites: Docker running, Rust toolchain
git clone https://github.com/evotech-bg/royak
cd royak
cargo build --release

# deploy nginx with 2 replicas
./target/release/royak apply examples/nginx.yaml

# see the swarm
./target/release/royak get pods

Linux or macOS · Docker (or Colima/OrbStack — DOCKER_HOST is honoured) · Rust 1.75+