v3/implementation/adrs/ADR-058-self-contained-ruflo-rvf-appliance.md
| Field | Value |
|---|---|
| Status | Proposed |
| Date | 2026-02-28 |
| Authors | Claude Flow Team |
| Supersedes | — |
| Related | ADR-057 (RVF Native Storage), ADR-054 (RVF Plugin Marketplace), ADR-056 (agentic-flow v3 Integration), ADR-017 (RuVector Integration) |
Ruflo v3.5 requires the user to have Node.js 20+, npm, Claude Code CLI, API keys, and a properly configured OS environment. This means:
A single ruflo.rvf file that contains everything needed to run the full Ruflo platform:
ruflo.rvf (self-contained appliance)
├── Linux microkernel (Alpine-based, ~5MB)
├── Node.js 22 runtime (~30MB stripped)
├── Claude Code CLI
├── Ruflo v3.5+ (all packages)
├── ruvLLM local inference OR API key vault
├── AgentDB with HNSW indexes
├── Pre-trained SONA patterns
├── 60+ agent definitions
├── MCP server (pre-configured)
└── Capability verification suite
One file. No install. No dependencies. Works offline with ruvLLM, or connects to cloud APIs.
The RVF (RuVector Format) binary format from ADR-057 already provides:
| RVF Feature | Appliance Use |
|---|---|
Magic bytes (RVF\0, RVEC, RVFL, RVLS) | Section identification within appliance |
| Header + payload binary layout | Metadata + compressed filesystem layers |
| Atomic write (tmp + rename) | Safe appliance updates |
| CRC32/SHA256 integrity | Appliance verification |
| Streaming reads | Boot without full decompression |
Extending RVF to RVFA (RuVector Format Appliance) creates a unified format that Ruflo already understands natively.
RVFA (RuVector Format Appliance)┌─────────────────────────────────────────────────┐
│ Magic: RVFA (4 bytes) │
│ Version: u32 (4 bytes) │
│ Header Length: u32 (4 bytes) │
├─────────────────────────────────────────────────┤
│ Header (JSON): │
│ name, version, created, arch, platform │
│ sections: [{ id, type, offset, size, sha256 }]│
│ boot: { entrypoint, args, env } │
│ models: { provider, engine, config } │
│ capabilities: [list of verified caps] │
├─────────────────────────────────────────────────┤
│ Section 0: KERNEL (compressed rootfs) │
│ Alpine Linux 3.23 minimal + busybox │
│ /sbin/init → ruflo-init (PID 1) │
├─────────────────────────────────────────────────┤
│ Section 1: RUNTIME (compressed) │
│ Node.js 22 (stripped, no npm) │
│ Claude Code CLI binary │
├─────────────────────────────────────────────────┤
│ Section 2: RUFLO (compressed) │
│ @claude-flow/cli + shared + guidance │
│ All 26 commands, 140+ subcommands │
│ 60+ agent definitions │
│ 17 hooks + 12 workers │
│ MCP server (pre-configured, stdio + SSE) │
├─────────────────────────────────────────────────┤
│ Section 3: MODELS (compressed, optional) │
│ ruvLLM engine (GGUF quantized models) │
│ OR: encrypted API key vault (.env.enc) │
│ OR: hybrid (local small + cloud large) │
├─────────────────────────────────────────────────┤
│ Section 4: DATA (RVF native) │
│ AgentDB with pre-built HNSW indexes │
│ Pre-trained SONA patterns │
│ Plugin registry snapshot │
│ Capability verification checksums │
├─────────────────────────────────────────────────┤
│ Section 5: VERIFY (plaintext) │
│ Built-in capability test suite │
│ Expected results manifest │
│ Self-test entrypoint │
├─────────────────────────────────────────────────┤
│ Footer: SHA256 of all sections (32 bytes) │
└─────────────────────────────────────────────────┘
Three model configurations, selected at build time:
| Profile | Models Included | Size | Offline | Use Case |
|---|---|---|---|---|
offline | ruvLLM + Qwen2.5-Coder-3B-Q4 + Phi-3-mini-Q4 | ~4GB | Full | Air-gapped, edge, demos |
hybrid | ruvLLM + Phi-3-mini-Q4 + API vault | ~2GB | Partial | Local routing + cloud for complex tasks |
cloud | API key vault only (no local models) | ~80MB | No | Minimal size, full cloud |
ruvLLM is the local language model inference engine from the RuVector ecosystem. It extends the existing @ruvector packages (core, router, sona, attention) with on-device LLM inference:
ruvLLM Architecture (extends @ruvector):
├── @ruvector/core — vector database, Q-learning router, AST analysis
├── @ruvector/router — ML-based intelligent task routing (~80% accuracy)
├── @ruvector/sona — Self-Optimizing Neural Architecture (<0.05ms)
├── @ruvector/attention — Flash Attention (2.49x-7.47x speedup)
├── @ruvector/micro-hnsw-wasm — HNSW vector search (WASM)
└── ruvLLM (new):
├── GGUF model loader (llama.cpp compatible)
├── KV-cache with RVF persistence
├── Token streaming over stdio/SSE
├── Automatic model selection by task complexity
│ ├── Tier 1: Agent Booster (WASM, <1ms) — simple transforms
│ ├── Tier 2: Phi-3-mini-Q4 (local, ~200ms) — routing, classification
│ └── Tier 3: Qwen2.5-Coder-3B-Q4 (local, ~2s) — code generation
└── Fallback to cloud API if local confidence < threshold
ruvLLM bridges the gap between RuVector's vector intelligence (search, routing, learning) and full language model inference, keeping everything in the same ecosystem.
API Key Vault (for cloud profiles):
.env.enc (AES-256-GCM encrypted)
├── ANTHROPIC_API_KEY → Claude Sonnet/Opus
├── OPENAI_API_KEY → GPT-4/Codex (dual-mode)
├── GOOGLE_API_KEY → Gemini (fallback)
└── Decryption: passphrase at boot OR hardware key
1. ruflo-appliance load ruflo.rvf
2. Verify RVFA magic bytes + footer SHA256
3. Extract KERNEL section → mount as rootfs
4. Extract RUNTIME section → /usr/local/bin/
5. Extract RUFLO section → /opt/ruflo/
6. Mount DATA section (read-write overlay)
7. Load MODELS section:
- If ruvLLM: start inference server on unix socket
- If API vault: decrypt keys, set env vars
- If hybrid: start local + configure cloud fallback
8. Run VERIFY section → self-test all capabilities
9. Start MCP server (stdio or SSE based on config)
10. Ready for agent orchestration
| Mode | Command | Description |
|---|---|---|
| Run | ruflo-appliance run ruflo.rvf | Boot and enter interactive CLI |
| MCP | ruflo-appliance mcp ruflo.rvf | Boot as MCP server (stdio) |
| Verify | ruflo-appliance verify ruflo.rvf | Run full capability test suite |
| Extract | ruflo-appliance extract ruflo.rvf ./out/ | Unpack all sections |
| Build | ruflo-appliance build --profile offline | Create new appliance |
| Update | ruflo-appliance update ruflo.rvf --section RUFLO | Hot-patch one section |
| Inspect | ruflo-appliance inspect ruflo.rvf | Show header + section manifest |
The appliance runs in one of three isolation levels:
| Level | Technology | Overhead | Security |
|---|---|---|---|
| Container | OCI/Docker (default) | ~50MB RAM | Namespace + cgroup isolation |
| MicroVM | Firecracker/Cloud Hypervisor | ~128MB RAM | Full VM isolation |
| Native | Direct execution (dev only) | ~30MB RAM | Process-level only |
Container mode (default):
# The .rvf file IS the container image
ruflo-appliance run ruflo.rvf
# Equivalent to:
# docker run --rm -it ruflo:self-contained
The appliance includes a built-in verification suite that tests every capability of Ruflo + Claude Flow. This runs automatically at boot (Section 5: VERIFY) and can be triggered manually.
| # | Category | Critical Checks | What It Proves |
|---|---|---|---|
| 1 | CLI Core | --version, --help, version match | Binary integrity |
| 2 | Doctor | 14 health checks, --fix | System diagnostics |
| 3 | Init System | settings.json, helpers, agent teams config | Project scaffolding |
| 4 | Memory Operations | store, list, search, retrieve, delete, TTL | AgentDB + RVF backend |
| 5 | Config Management | show, get, set, list | Configuration system |
| 6 | Session Management | start, status, end, list | Session persistence |
| 7 | Agent System | list, spawn, status, pool | Agent lifecycle |
| 8 | Swarm Coordination | init, status, topologies | Multi-agent orchestration |
| 9 | Task System | create, list, assign | Task management |
| 10 | Hooks System | list, route, pre-task, workers, statusline | Self-learning pipeline |
| 11 | Security | scan, audit, validate | Input validation, CVE checks |
| 12 | Performance | metrics, benchmark | Profiling |
| 13 | Neural/Intelligence | status, patterns | SONA + MoE |
| 14 | Embeddings | embed, search | Vector generation |
| 15 | Workflow System | list, templates | Workflow engine |
| 16 | Daemon | status, start | Background workers |
| 17 | Claims Authorization | list, check | RBAC |
| 18 | Migration | status | V2→V3 migration |
| 19 | Plugins | list | Plugin registry |
| 20 | MCP Server | help, list, stdio transport | MCP protocol |
| 21 | Completions | bash, zsh | Shell integration |
| 22 | Status | system status | Health monitoring |
| 23 | Hive-Mind | status | Byzantine consensus |
| 24 | Process Management | list | Background processes |
| 25 | Cross-Feature Integration | store→search→retrieve→delete cycle | End-to-end data flow |
| # | Category | Checks | What It Proves |
|---|---|---|---|
| 26 | RVF Format | magic bytes, header parse, section integrity | Binary format correctness |
| 27 | ruvLLM Inference | model load, tokenize, generate, stream | Local LLM works offline |
| 28 | API Vault | decrypt, key validation, provider connectivity | Cloud API access |
| 29 | Boot Integrity | SHA256 verification, section checksums | Tamper detection |
| 30 | Isolation | namespace check, cgroup limits, filesystem | Security boundaries |
| 31 | Agent Swarm E2E | spawn 4 agents → coordinate → produce output | Full orchestration |
| 32 | MCP E2E | JSON-RPC init → tool call → response | Protocol compliance |
| 33 | Persistence | write data → reboot → verify data survives | RVF durability |
| 34 | Offline Mode | disconnect network → run full workflow | Air-gap capability |
| 35 | Hot Update | patch RUFLO section → verify new version | Live update |
╔══════════════════════════════════════════════════════════╗
║ Ruflo Appliance v3.5.2 — Full Capability Verification ║
║ Format: RVFA v1 | Profile: offline | Arch: x86_64 ║
║ Kernel: Alpine 3.23 | Node: 22.22.0 | ruvLLM: 0.1.0 ║
╚══════════════════════════════════════════════════════════╝
═══ 1. CLI Core ═══
✓ ruflo --version
✓ ruflo --help
✓ version is 3.5.2
═══ 2. Doctor ═══
✓ doctor runs (14/14 checks)
...
═══ 26. RVF Format ═══
✓ RVFA magic bytes valid
✓ header JSON parses correctly
✓ all 6 sections present
✓ section SHA256 checksums match
✓ footer hash matches computed hash
═══ 27. ruvLLM Inference ═══
✓ model loaded (Phi-3-mini-Q4, 2.3GB)
✓ tokenizer functional (32000 vocab)
✓ generation produces valid output
✓ streaming tokens arrive in <100ms
✓ KV-cache persists across calls
══════════════════════════════════════════════════
RESULTS: 95/95 passed, 0 failed, 3 warnings
★ APPLIANCE FULLY VERIFIED
══════════════════════════════════════════════════
# Build offline appliance (includes local models)
ruflo-appliance build \
--profile offline \
--arch x86_64 \
--models "phi-3-mini-q4,qwen2.5-coder-3b-q4" \
--output ruflo-offline.rvf
# Build cloud appliance (API keys only)
ruflo-appliance build \
--profile cloud \
--api-keys .env \
--output ruflo-cloud.rvf
# Build hybrid appliance
ruflo-appliance build \
--profile hybrid \
--models "phi-3-mini-q4" \
--api-keys .env \
--output ruflo-hybrid.rvf
Stage 1: KERNEL
├── Pull alpine:3.23 rootfs
├── Install busybox, dumb-init
├── Strip to <5MB
└── Compress with zstd -19
Stage 2: RUNTIME
├── Download Node.js 22 (linux-x64-musl)
├── Strip debug symbols, remove npm/corepack
├── Include Claude Code CLI binary
└── Compress (~30MB → ~12MB)
Stage 3: RUFLO
├── npm pack ruflo@latest --omit=optional
├── Include all CLI commands + agent defs
├── Pre-configure MCP server
└── Compress (~9MB → ~3MB)
Stage 4: MODELS (profile-dependent)
├── offline: Download GGUF models, build ruvLLM
├── hybrid: Download small model + encrypt keys
└── cloud: Encrypt API keys only
Stage 5: DATA
├── Initialize AgentDB with RVF backend
├── Build HNSW indexes for default patterns
├── Snapshot pre-trained SONA weights
└── Cache plugin registry
Stage 6: VERIFY
├── Bundle test script (sh, no dependencies)
├── Generate expected-results manifest
└── Include checksum of all sections
Final: Assemble RVFA
├── Write magic + version + header
├── Append all sections with offsets
├── Compute and append footer SHA256
└── Output: ruflo.rvf
| Profile | Sections | Compressed Size |
|---|---|---|
cloud | Kernel + Runtime + Ruflo + Data + Verify | ~60MB |
hybrid | All + Phi-3-mini-Q4 | ~2GB |
offline | All + Phi-3 + Qwen2.5-Coder-3B | ~4GB |
┌──────────────────────────────────────────────────────────────┐
│ ruflo.rvf (RVFA) │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ KERNEL: Alpine Linux 3.23 (~5MB) │ │
│ │ ┌──────────────────────────────────────────────────┐ │ │
│ │ │ RUNTIME: Node.js 22 + Claude Code CLI │ │ │
│ │ │ ┌──────────────────────────────────────────────┐│ │ │
│ │ │ │ RUFLO v3.5+ ││ │ │
│ │ │ │ ├── 26 CLI commands (140+ subcommands) ││ │ │
│ │ │ │ ├── 60+ agent definitions ││ │ │
│ │ │ │ ├── 17 hooks + 12 workers ││ │ │
│ │ │ │ ├── MCP server (215 tools) ││ │ │
│ │ │ │ ├── AgentDB + HNSW (RVF backend) ││ │ │
│ │ │ │ └── Security + Claims + Plugins ││ │ │
│ │ │ └──────────────────────────────────────────────┘│ │ │
│ │ │ ┌──────────────────────────────────────────────┐│ │ │
│ │ │ │ MODELS ││ │ │
│ │ │ │ ├── ruvLLM inference engine ││ │ │
│ │ │ │ ├── Local: Phi-3 / Qwen2.5-Coder (GGUF) ││ │ │
│ │ │ │ └── Cloud: encrypted API key vault ││ │ │
│ │ │ └──────────────────────────────────────────────┘│ │ │
│ │ └──────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ DATA: AgentDB + SONA patterns + Plugin registry │ │
│ └────────────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ VERIFY: 95-check capability suite + checksums │ │
│ └────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
│ │ │
┌────┴────┐ ┌────┴────┐ ┌────┴────┐
│Container│ │MicroVM │ │ Native │
│ (OCI) │ │(Firecrk)│ │ (dev) │
└─────────┘ └─────────┘ └─────────┘
User Task
│
▼
┌─────────────────┐
│ Complexity Check │
│ (hooks route) │
└────────┬────────┘
│
┌────┴────────────────────────┐
│ │
▼ ▼
Simple (<30%) Complex (>30%)
│ │
▼ ▼
┌──────────┐ ┌─────────────┐
│ Tier 1: │ │ ruvLLM local?│
│ Agent │ └──────┬──────┘
│ Booster │ Yes │ No
│ (WASM) │ ┌────┴────┐
│ <1ms, $0 │ │ │
└──────────┘ ▼ ▼
┌──────────┐ ┌──────────┐
│ Tier 2: │ │ Tier 3: │
│ Phi-3 │ │ Cloud API│
│ (local) │ │ (Sonnet/ │
│ ~200ms │ │ Opus) │
│ $0 │ │ 2-5s │
└──────────┘ └──────────┘
| Mechanism | Purpose |
|---|---|
| RVFA footer SHA256 | Tamper detection for entire appliance |
| Per-section SHA256 | Integrity of individual sections |
| Code signing (Ed25519) | Verify publisher identity |
| API key vault (AES-256-GCM) | Protect cloud credentials |
| Read-only rootfs | Prevent runtime modification of system files |
| Namespace isolation | Container/VM boundary enforcement |
| Seccomp profile | Restrict syscalls to minimum required |
Boot:
1. User provides passphrase OR hardware key
2. Derive AES key via Argon2id (memory-hard)
3. Decrypt .env.enc → load API keys into memory
4. Keys exist only in process memory (never on disk)
5. On shutdown: zero memory, drop keys
Hot Update Flow:
1. Download signed patch (.rvfp)
2. Verify Ed25519 signature against pinned public key
3. Verify patch targets correct appliance version
4. Apply patch to target section
5. Recompute section SHA256 + footer hash
6. Run VERIFY suite to confirm no regression
7. Atomic swap (old → .bak, new → active)
| Task | Description |
|---|---|
| Define RVFA binary spec | Magic bytes, header schema, section table |
ruflo-appliance build | Multi-stage builder with profile selection |
ruflo-appliance inspect | Header + section manifest viewer |
ruflo-appliance extract | Unpack all sections to directory |
| Cloud profile | Kernel + Runtime + Ruflo + encrypted keys |
| Task | Description |
|---|---|
ruflo-appliance run | Boot sequence with container isolation |
ruflo-appliance verify | 95-check capability suite |
ruflo-appliance mcp | MCP server mode (stdio + SSE) |
| DATA section | Pre-built AgentDB + HNSW + SONA |
| CI integration | Build appliance on every release |
| Task | Description |
|---|---|
| ruvLLM engine | GGUF model loader + KV-cache + streaming |
| Model routing | 3-tier routing (Booster → local → cloud) |
| Hybrid profile | Small local model + cloud fallback |
| Offline profile | Full local inference, no network |
| Offline verification | All 95 checks pass without network |
| Task | Description |
|---|---|
ruflo-appliance update | Hot-patch individual sections |
| Ed25519 signing | Code signing for appliance + patches |
| IPFS distribution | Publish appliances to decentralized storage |
| MicroVM support | Firecracker/Cloud Hypervisor isolation |
| Documentation | User guide, API reference, examples |
npx ruflo@latest)| Alternative | Reason Rejected |
|---|---|
| Docker image only | Requires Docker installed; no offline model support; not a single file |
| Flatpak/Snap | Linux-only packaging; no custom binary format; no model bundling |
| AppImage | Linux-only; no Windows/macOS; limited isolation |
| WebAssembly bundle | No filesystem access; can't run Claude Code CLI; no local models |
| Nix derivation | Requires Nix; steep learning curve; no model bundling |
| VM image (qcow2) | Too large; requires hypervisor; not portable |
RVFA provides the best balance of portability, size, isolation, and integration with the existing RVF ecosystem.