Architecture decisions
Short records of decisions that are expensive to reverse. To write one, follow
docs/playbooks/write-an-adr.md. Claude Code users can run /new-adr.
ADRs are history, so they’re never rewritten. When a later decision changes an earlier one, the earlier
ADR gets a banner at the top saying what still applies. Read the newest ADRs first: 0011 to 0020
define today’s product. ADRs keep the names of their time: 0001 to 0019 use the working name “Tensora”
(TENSORA_*, tensora.io/*, the tensora binary), and 0020 uses “TensoraFi”. The product is
Einsora; ADR-0020 and ADR-0021 map the old
identifiers to Einsora’s.
| # | Decision | Status |
|---|---|---|
| 0011 | Free for everyone: no pricing, no billing, open source | Accepted |
| 0012 | Deployment profiles: Solo, Lab, Datacenter | Accepted (SQLite store and local accounts built; the rest planned) |
| 0013 | Node agent and drivers; Apple Silicon Macs as first-class hosts | Accepted (machines, accelerators, Apple and CPU classes, per-platform runtimes, and the in-process agent in code; real drivers planned) |
| 0014 | Sharing idle compute: private, invite-only, community pools | Accepted (sharing level stored per machine; enforcement planned) |
| 0015 | Logs and transparency: complete, exportable, nothing hidden except secrets | Accepted (timeline, export, CLI built; output and activity logs planned) |
| 0016 | Agent protocol and machine placement: one long-polled Sync, desired state from the store, a runtime-neutral backend, placement in the controller |
Proposed (in-process agent, agent backend, and placement built; network transport Phase 2) |
| 0017 | Workload access and native drivers: open workloads through an access proxy at their own *.localhost host with one-time tickets; native drivers are supervised, sandboxed processes |
Proposed (proxy, process supervisor, and macos-native notebooks and MLX endpoints built) |
| 0018 | Linux Docker driver: local Engine API, owner-only containers, physical NVIDIA UUIDs, private socket access, durable recovery | Proposed (implemented; live Linux/CUDA validation pending) |
| 0019 | Driver-specific runtimes: choose by accelerator and driver; native CPU notebooks reserve Metal access explicitly | Proposed (implemented; real CPU/Metal notebook tests) |
| 0020 | Name and licence: the product is TensoraFi, renamed everywhere in one change; MIT licence | Accepted (name superseded by 0021; MIT still applies) |
| 0021 | Rename to Einsora: a US mark TENSORA is registered in the same class; every identifier renamed in one change | Accepted |
| 0001 | Kubernetes, KubeVirt, and the GPU Operator | Accepted; Datacenter profile only (0012) |
| 0002 | k3s with embedded etcd | Accepted; Datacenter profile only (0012) |
| 0003 | Go for the core platform, Python for the ML layer, TypeScript for the dashboard | Accepted |
| 0004 | Untrusted code runs only behind strong isolation (VMs, Kata) | Accepted; generalized by the trust matrix (0014) |
| 0005 | Longhorn, then Rook-Ceph | Accepted; Datacenter profile only (0012) |
| 0006 | Account usage on allocation, not utilization | Superseded in part by 0011 (no billing; accounting kept) |
| 0007 | Gateway API on Cilium | Accepted; Datacenter profile only (0012) |
| 0008 | The store owns intent, the runtime owns runtime state, a controller reconciles | Accepted; generalized by 0012 and 0013 |
| 0009 | Regions: one control plane, independent regional cells | Accepted; reframed for self-hosting by 0011 and 0012 (regions in the data model, catalog, API, and controller) |
| 0010 | Fallbacks: CPU placement and inference failover | Accepted; “billed” reads as “accounted” (0011) (placed class recorded and accounted; fallback placement planned) |
Statuses run Proposed → Accepted → (Superseded by NNNN | Deprecated). Never delete an ADR; supersede it.