Locara — Specification
This folder contains the technical specification for Locara: a framework + runtime + distribution layer for fully-local LLM applications on macOS.
The spec is organized as a sequence of focused documents, each covering one design surface. Read in order for a full picture; jump to specific files when working on that surface.
This is a living draft. Decisions marked (open) are unresolved and need pinning down. Decisions marked (committed) are settled — change them deliberately, with an ADR.
Want to know what’s actually shipped vs. what’s still aspirational?
See IMPLEMENTATION-STATUS.md — a single
table mapping every spec surface to ✅ shipped / 🚧 partial / 📝 stub /
❌ not started. Specs document intent; the status doc is ground truth.
Reading order
Foundations
Developer experience
| # | Document | What it covers |
|---|
| 05 | SDK | @locara/sdk API surface |
| 06 | CLI | locara command spec |
| 07 | Runtime | Tauri shell, sandboxing, app lifecycle |
| 08 | Storage | SQLite, sqlite-vec, zvec, schemas, migrations |
| 09 | Models | Model registry, content addressing, MLX/llama.cpp |
| 10 | Tools | Wasmtime + WASI tool execution runtime |
| 11 | Components | @locara/components distribution model |
Distribution + trust
| # | Document | What it covers |
|---|
| 12 | Registry | Submission flow, review pipeline, artifact storage |
| 13 | Security & Privacy | Secure-by-default synthesis; privacy-by-architecture |
| 14 | Trust & Safety | Signing, provenance, kill-switch, takedowns |
| 15 | Distribution | Install, update, sideload |
| 16 | Build | Build pipeline, code signing, notarization |
Project + operations
| # | Document | What it covers |
|---|
| 17 | Repo layout | Monorepo structure, crates, packages |
| 18 | Phasing | Milestones, what’s in each phase |
| 19 | Glossary | Definitions of terms |
Quality + policy
Engineering deep dives
Application-level features
Operations
| # | Document | What it covers |
|---|
| 40 | Operational Security | Identity, credential custody, escrow, succession, drills |
Concrete artifacts
Companion folders
../notes/ — Research notes on prior art (app stores, runtimes, frameworks). Cite here when justifying a design decision.../docs/adr/ — Architecture Decision Records. ADRs 0001 (Tauri), 0002 (llama.cpp v1, MLX v2), 0003 (open source + restricted commit access).../legal/ — Privacy policy, terms of service, DMCA policy. Drafts pending lawyer review.../website/content/manifesto.md — The public-facing pitch.../LICENSE — Apache 2.0.
Conventions
- (committed) — design decision is settled.
- (open) — decision is unresolved.
- (open: A vs B) — narrowed to options; needs choosing.
- Cross-references use relative links:
[CLI](./06-cli.md).
- Code blocks use realistic syntax even if APIs aren’t yet implemented — they document intent.
The three top-level lenses
When reading the spec, three ideas are central:
- Secure & private by default. Locara apps demonstrably can’t betray the user — capabilities are kernel-enforced, telemetry is zero, data stays local because operations are local. See 13-security-privacy.md, 03-capabilities.md, 14-trust-safety.md, 31-capability-analyzer.md.
- Agent-friendly by design. The framework is built assuming the developer pairs with an LLM coding assistant. Closed-catalog modalities + tooling, strongly-typed SDK, copy-in components, and
locara init --from-prompt are the concrete expressions. See 00-overview.md, 04-modalities.md.
- Local-first as structural advantage. The framework’s privacy story isn’t a policy — it’s an architectural property. Reads/writes happen on-device because that’s where the model, the database, and the tools live. See 13-security-privacy.md and the manifesto’s “Why local matters” section.
Out of scope (for v1)
- Mobile (iOS/Android). Architectural compatibility considered, but not shipping.
- Windows / Linux. Mac-first. Cross-platform after Mac is solid.
- Cloud-hybrid apps as default. Locara is local-first; cloud fallback is opt-in via
net capability.
- Payments processing. Apps charge via Mac App Store / Stripe / Lemon Squeezy.
- Real-time collaboration / multi-device sync. Single-device, single-user apps in v1.
- A general “agent framework.” Locara provides primitives; agents are user code.
- Daemon / shared model server. v1 = each app loads its own; v2+ adds the daemon.
- Localization (i18n). English-only v1; see 39-i18n.md.
How to contribute to the spec
When opening a PR that changes the spec:
- Update the relevant numbered document.
- If an
(open) is being resolved, mark it (committed) and add an ADR in ../docs/adr/.
- Update phasing if the change affects milestones.
- Cross-reference: if Document A’s decision affects Document B, update both.
Substantive changes go through the RFC process. Note that commit access to the canonical Locara repos is restricted — see ADR 0003.
Status
| Section | Status |
|---|
| Foundations (00–04) | Draft v0.1 |
| Developer experience (05–11) | Draft v0.1 |
| Distribution + trust (12–16) | Draft v0.1 |
| Project + operations (17–19) | Draft v0.1 |
| Quality + policy (20–29) | Draft v0.1 |
| Engineering deep dives (30–34) | Draft v0.1 |
| Application-level features (35–39) | Draft v0.1 |
| ADRs | 3 accepted (Tauri, llama.cpp v1, restricted commit access) |
| Legal | Draft, lawyer review pending |
| Manifesto | Draft v0.2 |
All documents are draft. Internal review pass next; public release at end of phase 0 (after name + domain are locked, lawyer reviews legal docs, ADRs are filled in for remaining (open)s).