Lucius runs one large language model split across the Apple devices you already own — pipeline-parallel over your Wi-Fi, behind a single OpenAI-compatible endpoint.
No cloud. No account. Nothing leaves your network.

_{App Store release: soon. Today, you build it yourself — see Build & run.}

Website · How it works · Trust model · Build & run · Developing · Security · Contributing

There is one app: Lucius Node (iOS). Nodes form a mutual-TLS fabric over the LAN; any node can self-elect as the hub — the orchestrator that holds the full model, fans out per-shard slices, builds the plan, runs the per-token pipeline, and serves a browser admin cockpit. Clients talk to the hub's endpoint and never know the model is distributed.

One app, every device. Lend a device's compute while it's open and charged — even a retired one.

Any node can lead. Promote it and it becomes the hub — orchestrator, certificate authority and cockpit included.

Joining starts in the room. The QR carries a one-time token + the fleet's CA anchor; admission is hardware-attested.

Run the fleet from a browser

The hub serves its own admin cockpit on your network — no hosted dashboard, no account. Point any browser on your Wi-Fi at the hub: fleet constellation, model library, live sessions with per-session API keys, and the fleet-event stream.

_{A run recorded on real hardware, replayed in the cockpit — a device drops, the hub re-deals its layers, the device rejoins. Play with it live on the product page.}

Highlights

Verified end-to-end on a real multi-device iPhone/iPad fleet — 4-way shard, coherent replies, each device holding only its slice.

• 🧩 One slice per device — the hub's pure-Swift safetensors slicer cuts and remaps each shard's layers; no device ever stores (or transfers) the whole model.
• ⚖️ Capability-weighted planning — layers ∝ each device's measured layers/s benchmark, so mismatched devices each pull exactly their weight. Fleets are auto-discovered over Bonjour.
• 🔁 Ring decode — after the first token the tail re-arms the head directly; the hub is out of the per-token loop entirely.
• 👑 Movable hub — the hub is a role, not a machine: any node can promote, and the fabric survives the hub moving.
• 🔐 The hub is the certificate authority — per-device mTLS leaves minted on-device, App-Attest-gated admission, revocation that sticks. No hosted CA, no account, no cloud.
• 🔌 OpenAI-compatible — point any client at /{slot}/v1; per-session endpoints with Bearer keys minted in the cockpit.
• 🧠 Generalized engine — dense Qwen3/Llama plus MoE/hybrid families (Qwen3.5, DeepSeek-V2-Lite, OLMoE, Ling, LFM2-MoE) through one ArchitectureRegistry.

How it works

A model is selected once on the hub. The hub downloads the full model once and hands each device only its slice, so no device ever stores the whole model.

flowchart LR
    A["Promote a Node —<br>it becomes the hub"] --> B["Pick a model<br>in the cockpit"]
    B --> C["Hub downloads the<br>full model, once"]
    C --> D["Capability-weighted plan:<br>layers ∝ measured layers/s"]
    D --> E["Pure-Swift safetensors slicer<br>cuts + remaps each shard's slice"]
    E --> F["Each Node fetches ONLY its slice<br>over mTLS — disk cost: one slice"]

Loading

Generation is a ring: after the first token, the tail re-arms the head directly — the hub is not in the per-token loop.

flowchart LR
    CL["OpenAI client<br>POST /v1/chat/completions"] --> H
    H["HEAD shard<br>chat template + embed<br>+ layers 0…k"] -->|activations| M["MID shard(s)<br>layers k…m"]
    M -->|activations| T["TAIL shard<br>layers m…N + norm<br>+ LM head + sample"]
    T -->|"re-arms the head directly,<br>until EOS / max tokens"| H
    T -->|streamed tokens| CL

Loading

• Identity is LAN-local: the hub mints a per-tenant TenantCA on-device (P-256 root, Keychain), serves the fabric on a leaf it issues itself, and issues each peer a leaf over POST /enroll/lan. Peers pin the hub's CA anchor (delivered out of band in the join QR). All fabric + inference traffic is mutual-TLS on the LAN; nothing contacts the cloud.
• Slice distribution (ModelHub + SafetensorsSlicer, SliceFetch in the engine): the hub serves a manifest + a remapped slice (+ tokenizer/chat-template for head/tail). A device's on-disk + transfer cost is one slice, not a full copy.
• Capability-weighted, auto-discovered: nodes announce capabilities (a measured layers/s benchmark, shardStatus, node↔hub latency); shards are sized ∝ compute. No manual endpoint list.

Terminology

• Lucius Node — the iOS app (target Node, product LuciusNode.app). Runs one contiguous range of the model's transformer layers on-device (MLX). Contributes only while foreground + powered (charging, or battery above a healthy floor) + on the network — never in the background. The battery floor is hysteretic (joins at ≥ 40%, serves down to 30%), so a brief charge sag under inference load doesn't drop the node mid-generation.
• Hub — a Node that has been promoted (NodeHubHost running HubRuntime.HTTPServer on-device). It exposes /v1/chat/completions, holds the full model + fans out per-shard weight slices, builds the shard plan, runs the pipeline, is its own certificate authority, and serves the admin cockpit. The hub can move to any node.
• Shard — one layer range of the model, hosted by a worker.

Trust model

The LAN is the trust boundary. Lucius 0.1 is LAN-only: nothing contacts the cloud, and the security design assumes the local network is yours.

• Fabric control + inference (:8765, node :9100) — mutual TLS, always. Every device presents a short-lived per-device certificate issued by the hub's on-device TenantCA; peers pin the CA anchor delivered in the join QR. A device that isn't enrolled (or is revoked) cannot speak to the fabric at all.
• Join bootstrap (POST /enroll/lan on :8770) — plaintext, single-use. The QR shown on the hub's screen carries a one-time join token (re-rolled the moment it is spent) plus the CA anchor; physical sight of the hub screen is the admission credential. The standing tenant credential rides the response, never the QR.
• Hardware-attested issuance (App Attest) — the only admission path. The hub verifies an App Attest hardware attestation before issuing any leaf and pins the attested key: renewals then require an offline Secure-Enclave assertion against that pin, and revoking the device kills its renewals. Devices that cannot attest (Macs, Simulator) cannot join — every fleet member is a real, attested iOS device. Honest caveat: generating the attestation contacts Apple, so a device's first join needs internet once — renewals and steady-state operation stay fully offline.
• Identity survives app reinstall — "Leave fleet" is the reset. Fabric identity (the leaf, its key, the pinned App Attest key id, the CA anchor — and on a hub, the tenant CA) lives in the device Keychain, which iOS keeps across app deletion. Deleting and reinstalling the app therefore resumes membership; the in-app Leave fleet action is the real identity wipe. A wiped device that re-promotes mints a NEW namespace + CA — a new fleet, not the old one — and nodes never silently defect: a node provisioned into one fleet ignores another fleet's hub until you scan that hub's QR.
• Admin cockpit (:8775) — plaintext HTTP on the LAN, by design. Browser-trusted TLS for a bare LAN IP would require a publicly-anchored certificate chain, which a LAN-only system cannot mint. Access is gated by pairing-token / passkey sign-in (session cookie). Treat the cockpit as what it is: an admin surface on a trusted network. Do not port-forward :8775 (or anything else) to the internet — the plaintext cockpit and its session cookie are only defensible inside the LAN boundary.
• Client API (:8770/{slot}/v1) — plaintext on the LAN, gated by per-session Bearer keys minted in the cockpit.

What this deliberately does not defend against: a hostile device already on your Wi-Fi observing plaintext cockpit/client traffic or replaying its cookies. If your LAN has untrusted tenants, don't run Lucius on it — the mTLS fabric keeps them out of the compute, but the admin and client planes trust the network.

Build & run

git clone https://github.com/XanaduCyber/lucius-oss.git

MLX's Metal library is produced by Xcode's toolchain, not swift build — install once: xcodebuild -downloadComponent MetalToolchain.

# shared-package tests
cd Packages/FabricCore && swift test
cd Packages/HubRuntime && swift test
cd Packages/NodeRuntime && swift test

# build + install Lucius Node (iOS device) → LuciusNode.app
cd Apps/iOS && xcodebuild -workspace Node.xcworkspace -scheme Node \
  -destination 'generic/platform=iOS' -derivedDataPath /tmp/node-dd \
  -allowProvisioningUpdates DEVELOPMENT_TEAM=<team> SWIFT_ENABLE_EXPLICIT_MODULES=NO build
xcrun devicectl device install app --device <UDID> \
  /tmp/node-dd/Build/Products/Debug-iphoneos/LuciusNode.app

devicectl … process launch is unreliable — install works, but launch the app by tapping it. On each device the Node announces and joins the fabric; promote one to hub, then drive a run from the admin cockpit (or the headless control API). Fleet members are attested iOS devices only — Modules/Sharding/ShardLab is a macOS development harness (local shard-worker + model gating), not a way to join a fleet.

Building your own fork

The project's bundle IDs (com.xanaducyber.lucius.*) and App Attest app ID belong to Xanadu's Apple developer team. To build and run your own fleet, set your own DEVELOPMENT_TEAM and bundle identifier — App Attest attestations are verified against the hub's configured <TeamID>.<bundleID>, so a fork attests against its app ID, not ours. Admission is attested-only: a build that cannot App Attest (e.g. Simulator) cannot join a fleet.

Repository

This repo is self-contained Lucius — the iOS-device LLM-sharding fabric. Packages/ is the runtime core (FabricCore → NodeRuntime/HubRuntime → HubUI), Modules/ holds feature modules (each standalone-buildable), and tests/ holds the black-box harnesses.

Repository layout — what lives where

Apps/iOS/                     The iOS app "Lucius Node" (hosts ShardEngine.ShardWorker; can self-elect
  Node.xcodeproj                as hub via NodeHubHost + HubRuntime) and its workspace (Node.xcworkspace)
  Node.xcworkspace
Packages/FabricCore/          Shared schema: OpenAI DTOs, ShardPlan/ShardingStrategy, shard protocol
                              (load/step/slice DTOs, Activation), NodeCapabilities, endpoints, and the
                              crypto primitives (FabricCore, FabricSecurity, FabricAttest — incl. TenantCA)
Packages/NodeRuntime/         The zero-module node runtime (NodeModel) — depends only on FabricCore
Packages/HubRuntime/          The hub runtime (HTTP server, PipelineCoordinator, ModelHub, cockpit server)
Packages/HubUI/               The hub SwiftUI surface (shared constellation/fleet/session views)
Modules/Sharding/ShardEngine/ Sharding engine (iOS + macOS): generalized MLX forward
                              (ArchitectureRegistry — Qwen3/Llama dense + MoE/hybrid decoders),
                              ShardSlice, ShardWorker actor, SliceFetch (fetch slice from the hub)
Modules/Sharding/ShardLab/    macOS dev harness/CLI: local shard-worker + model gating (dev only —
                              Macs are not fleet members; admission is attested iOS devices)
Modules/XanaduUI/             Shared SwiftUI design system (brand tokens + primitives)
assets/                       Brand marks (hero.svg, logo.svg, banner.webp) + app renders for this README
Scripts/generate_projects.rb  Regenerates the Node .xcodeproj/.xcworkspace from sources

Xcode project + workspace are generated from sources via Scripts/generate_projects.rb (uses the xcodeproj gem). Re-run after adding/removing Swift files; never hand-edit pbxproj. The scheme is Node; the product is LuciusNode.app.

Some code comments cite claudedocs/*.md design documents — those are internal engineering notes that are not part of this repository.

Developing

docs/DEVELOPMENT.md walks the contributor loops fastest-first: package unit suites, engine work on your Mac's GPU via ShardLab (no devices needed), the backend-free cockpit harness, the Simulator's honest limits, and the real-device workflow.

In progress: on-device hub election; full-model replication so a promoted hub always has the weights to resume a run.

License

Lucius is licensed under the Apache License 2.0. Copyright © 2026 Xanadu Cybersecurity and Intelligent Systems Ltd, trading as Xanadu Cyber. See CONTRIBUTING.md before opening a pull request, and SECURITY.md for vulnerability disclosure.

_{A Xanadu Cyber product · built in Scotland 🏴󠁧󠁢󠁳󠁣󠁴󠁿}