OptimalOS Fabric
Fabric is the redesign of optimal.miami from a Pi-only stack into a cloud control plane on Hetzner that routes sessions to paired user-owned compute devices, with a flagship credential vault and a Bloomberg-Terminal-meets-Project-Hail-Mary cockpit. Phase 10 shipped on 2026-05-03/04; tonight (2026-05-05) the deployment-mode split landed (commit bf69427) so optimal.miami and fabric.optimal.miami now serve the same bundle, gated by hostname + DEPLOYMENT env. 40 commits on optimalOS and 7 on optimal-cli were pushed to origin/clenis. Vault migrations are live, six recipients are active (iPad / MacBook Air M1 / Windows Chrome × browser+recovery), and the Hetzner deploy procedure is proven.
Why this exists
The Pi was thermal-throttling at 86 °C with no fan and took two OOM blackouts in early May 2026. There's no SPOF protection when the Pi is the entire stack. Fabric fixes that by:
- Making Hetzner CX32 (€5.83/mo, Debian 12, 7.6 GB RAM) the primary control plane. Cloud is intentionally thin — it never holds heavy compute or plaintext credentials.
- Making the Pi a paired secondary device. Devices dial out over WebSocket (Anthropic / Cursor pattern); cloud routes browser sessions to the best-fit device.
- Putting credentials in a multi-recipient
age-encrypted vault that a server compromise cannot decrypt — only registered passkeys + recovery phrase can.
How the pieces fit
- Cloud (Hetzner) —
https://fabric.optimal.miamivia Cloudflare Tunnel. Holds JWT auth, WebSocket multiplex, vault ciphertext, session router. Never holds plaintext credentials. - Devices (Pi, laptop, future Mac) — long-lived WebSocket dial-out to cloud. Run harness adapters (Claude Code, Kimi, Codex, OpenClaw, OpenCode). Hold device-private vault key for in-session credential decrypt.
- Browser — fingerprinted; passphrase + WebAuthn passkey registered once; subsequent unlocks are passphrase-only inside a 30-day trust window.
- MOTHER — parent AI on the highest-RAM paired device, runs a local quantized model (Ollama / llama.cpp / vLLM). v1 is narrate + suggest only.
- Cockpit (Phase 14, pending) — amber-on-black, panels-not-streams, mobile-first iPhone Safari with Web Speech + Web Push + passkeys. Two-screen: TOPO (devices = planets, sessions = ships, credentials = fuel depots) and BOARD (kanban).
Status at a glance
| Layer | Phase | Status |
|---|---|---|
| Vault crypto + schema + routes + UI + dashboard | 10a-1..10a-5, 10a-7 | ✓ Shipped |
| Hetzner provisioning + cloud-mode build + JWT/pairing/invite | 10b-1..10b-3 | ✓ Shipped |
| Device daemon + WS multiplex + e2e smoke + wire contract | 10c-1..10c-3 + 10c-1.1 | ✓ Shipped |
| Vault migrations on Supabase (5 tables 200 OK) | 10a-2 deploy | ✓ Shipped 2026-05-04 |
| iPad enrolled as second recipient (browser + recovery rows) | vault ceremony | ✓ Walked end-to-end 2026-05-04 |
Add Entry UI (drawer) + optimal vault add CLI | 10a-6 | ✓ Shipped (c3f3a7d + optimal-cli lib/vault/) |
| Claude Code full harness adapter | 11-1 | ✓ Shipped (d90a049) |
| Other harness adapters (Kimi / Codex / OpenClaw / OpenCode) | 11-2 | ✓ Shipped 2026-05-05 |
| Capability-aware routing | 12-1 | ✓ Shipped 2026-05-05 |
| Sessions tab — minimal session-start UI | 14-1 (thin slice) | ✓ Shipped (85d8226) |
| TOPO renderer (devices/sessions/credentials map) | 14-2 | ⏳ Pending — only Phase 14 piece left |
| BOARD kanban panel | 14-3 | ✓ Shipped 2026-05-05 |
| Fuel meter (THROUGHPUT / MISSION / YIELD, top:44px) | 14-4 | ✓ Shipped 2026-05-05 |
| Cockpit terminal lock-in | 14-5 | ✓ Shipped 2026-05-05 |
| Deployment-mode split (single bundle, hostname-gated) | infra | ✓ Shipped 2026-05-05 (bf69427) |
40 commits pushed to origin/clenis (optimalOS) | infra | ✓ Done 2026-05-05 |
7 commits pushed to origin/clenis (optimal-cli) | infra | ✓ Done 2026-05-05 |
| 6 active vault recipients (iPad/MacBook M1/Windows × browser+recovery) | ceremony | ✓ Live 2026-05-05 |
| 7 of 8 threat-audit P1s closed | security | ✓ 2026-05-05 |
Deploy-to-Hetzner procedure (pnpm build:cloud → rsync → restart) | infra | ✓ Proven end-to-end |
Pi paired as Fabric device recipient | kanban 8f84c30e | ⏳ Pending — optimal pair CLI exists (c132faf, 61b296d), ceremony not walked |
| TPM/SE device-key sealing | 12-2 | ⏳ Pending |
| OAuth Device Authorization Grant (replaces token-paste) | 13a-1 | ⏳ Pending |
| WebAuthn gates on destructive ops | 13b-1 | ⏳ Pending |
| Self-host Supabase/n8n/Strapi/Phoenix on Hetzner | 15-1..15-3 | ⏳ Pending |
| AI self-mod (bot-worktree → phone-push approval) | 16-1..16-2 | ⏳ Pending |
| Hosted SaaS billing | 17-1 | ⏳ Pending |
Quick start
New to Fabric? Go from "what is this" to "I have a credential in the vault" in under 5 minutes: Quickstart.
Where to read more
This site synthesizes the working source-of-truth docs that live in ~/.optimalos/transfers/fabric-design/ and ~/.openclaw/workspace/optimalOS/docs/superpowers/. Those are the canonical specs; pages here link out to them rather than duplicating.
- Quickstart — 5-minute walkthrough from sign-in to first vault entry
- Architecture — physical layout, transport contract, session flow
- Deployment modes — single bundle, hostname-gated; how
optimal.miami(legacy) andfabric.optimal.miami(fabric) split at runtime - OptimalVault — crypto core, ceremony, threat model
- Cockpit & MOTHER — TOPO/BOARD UX, fuel meter, MOTHER authority
- Phase Status — what's working, what's left to build, what's left to test
- Runbook — sanity checks, vault-migration push, Hetzner SSH, common breakages
Key constraints (locked)
- Cloud: Hetzner CX22/32 + Cloudflare Tunnel (orange-cloud + WAF + DDOS) + Caddy (Caddy unused for tunnel path; cloudflared talks directly to OptimalOS:3000)
- Transport: plain
ws+ NDJSON + JWT inSec-WebSocket-Protocol+ device-dials-out + correlation IDs - Vault:
agemulti-recipient (BSD-3, Filippo Valsorda); browser passphrase + WebAuthn passkey; BIP39 24-word recovery; canary blob detects non-deterministic authenticators - Pairing: token-paste v1; OAuth Device Authorization Grant in Phase 13
- MOTHER: local quantized model only — never cloud LLM
- Cockpit aesthetic: Bloomberg Terminal × Project Hail Mary × Alien × Interstellar; amber-on-black
- Hermes harness: dropped (Decision #24); catalog is CC + Kimi + Codex + OpenClaw + OpenCode
- Fuel meter: tokens not dollars — THROUGHPUT (5-min avg w/ sparkline) + MISSION (longest current uninterrupted streak) + YIELD (tasks/tokens today)
Full decision lock list: fabric-design/03-decision-ledger.md (25 decisions + post-Wave-1 amendments).