# Overview
> What the project exposes, its primary entry points, runtime assumptions, and links to the highest-value pages.
- Repository: egoist/lorca
- GitHub: https://github.com/egoist/lorca
- Human docs: https://grok-wiki.com/public/docs/egoist-lorca-2cf67495e5e6
- Complete Markdown: https://grok-wiki.com/public/docs/egoist-lorca-2cf67495e5e6/llms-full.txt
## Source Files
- `web/content/docs/index.mdx`
- `README.md`
- `ARCHITECTURE.md`
---
---
title: "Overview"
description: "What the project exposes, its primary entry points, runtime assumptions, and links to the highest-value pages."
---
Lorca ships three runnable surfaces: a Rust `lorca` CLI (localhost websocket + agent loop), a native macOS AppKit client that launches the bundled CLI, and an Expo phone app that pairs as a Device and speaks the relay protocol directly. Bots run on **Runners** you own (`macos`, `linux`, `windows`); phones and tablets (`ios`, `ipados`, `android`) are Devices only.
Production installs use `app.lorca` and `~/.lorca` on port `4862`. Dev installs use `app.lorca.dev`, `LORCA_HOME=~/.lorca-dev`, and port `4863`.
## What you get
| Surface | Path | Role |
| --- | --- | --- |
| macOS app | `macos/` | AppKit UI; speaks only to the local CLI over `127.0.0.1` websocket |
| CLI | `crates/cli` | Identity, pairing, E2E crypto, credentials, sync, `lorca serve` |
| Agent loop | `crates/agent` | Inference, tools, streaming, cancellation, bot orchestration |
| Relay | `crates/relay` | Store-and-forward API (axum + SQLite or Postgres); opaque blobs + public keys |
| Phone app | `mobile/` | Expo (iOS/Android); pairs as a Device; never a Runner |
| Website | `web/` | TanStack Start landing + MDX docs |
Persistent named bots, 1:1 chats, group chats (1–6 bots), handoff, and orchestration. Identity is a local key pair; Devices pair; traffic to the network is end-to-end encrypted.
## Runtime shape
```mermaid
flowchart TB
subgraph ui ["UI"]
App["Lorca.app / AppKit\nmacos/"]
Mobile["Phone app\nmobile/"]
end
subgraph local ["Local runtime"]
CLI["lorca CLI\ncrates/cli + crates/agent\nkeys + agent loop"]
end
subgraph net ["Network"]
Relay["Relay\ncrates/relay\npublic keys + ciphertext"]
end
App -->|"localhost websocket\n127.0.0.1"| CLI
CLI -->|"HTTPS\nsigned requests + blobs"| Relay
Mobile -->|"relay protocol\n(Device core)"| Relay
```
Hard constraints from the architecture:
1. The app talks **only** to the local CLI; the CLI holds keys, talks to the relay, and talks to models.
2. The CLI owns the agent loop (inference, tools, streaming, cancellation, orchestration).
3. The relay is zero-knowledge: opaque blobs and public keys; auth is a signature challenge.
4. A bot runs on **one** Runner (that Device’s CLI).
5. Provider credentials belong to the account and sync as an encrypted `credentials` blob to every paired Device.
## Primary entry points
### Dev commands
```bash
bun run dev # build CLI + app, launch app, rebuild on change; relay on 0.0.0.0:8787
bun run mobile # Expo Metro for the phone app
bun run mobile:ios # build/run iOS simulator (Xcode)
bun run relay # local relay on 0.0.0.0:8787 (point LORCA_RELAY_URL at it)
cargo test # agent loop, crypto, and SSE tests
bun run reset # stop everything; wipe identity, credentials, chats, prefs
bun run web # docs/landing at http://localhost:3000
```
### CLI as local service
The macOS app ships the CLI binary, starts `lorca serve` unless one already answers on the port, and restarts it if it exits. If the CLI is down, the app shows a native empty state with launcher status and the manual `lorca serve` command.
| Build | Home | Listen port |
| --- | --- | --- |
| Production (`Lorca` / `app.lorca`) | `~/.lorca` | `4862` |
| Development (`Lorca Dev` / `app.lorca.dev`) | `~/.lorca-dev` via `LORCA_HOME` | `4863` |
Self-host the relay anywhere; clients set `LORCA_RELAY_URL`. Pairing also accepts `lorca pair ` (or QR from the desktop app on phones).
## Devices vs Runners
Every Device records `os` in its machine metadata. Role is derived from `os` alone—no opt-in flag.
| `os` | Role | Can |
| --- | --- | --- |
| `macos`, `linux`, `windows` | **Runner** | Hold keys, sync, and run assigned bots/Jobs with account credentials |
| `ios`, `ipados`, `android` | Device | Hold keys, configure providers, read/write chats, create bots for Runners, pair Devices |
Peers learn Runner status from the decrypted metadata blob; the relay never learns which Devices are Runners.
## Identity and sync (short)
| Layer | Local | On the relay |
| --- | --- | --- |
| Master secret (32 bytes) | `~/.lorca/identity.json` (0600); backup as base32 phrase | — |
| Content / signing keys | Derived via HKDF from master | Public keys; identity id = `hash(pubkey)` |
| Account DEK | Encrypts roster, chats, messages, machine metadata, credentials | Sealed `key` blob to content pubkey |
| Machine keypair | `~/.lorca/machine.json` | Public keys, attested by the identity |
Recovery: restore the master secret from the backup phrase → re-derive content keys → unwrap DEKs from the relay. Unpairing (`device.unpair` / `identity.forget`) hits `DELETE /v1/machines/{machine_pubkey}`; revoked keys never authenticate again (`410 Gone`).
## Domain model (plaintext on Devices)
```
Identity 1──* Device
Device 1──* Bot (Runner only)
Identity 1──* Chat
Chat *──* Bot (dm: exactly 1 · group: 1–6)
Chat 1──* Message
Bot 1──* Routine
Device 1──* Plugin (MCP on a Runner)
Bot 1──* Job (turn on the bot's Runner)
```
A new account ships with **Chef** (chief of staff)—ordinary bot, renameable. Jobs are sealed envelopes to the Runner’s box key and deleted once run.
## AI providers
| Kind | Providers |
| --- | --- |
| API key | DeepSeek, Anthropic, OpenCode Zen, OpenCode Go |
| Subscription | ChatGPT, Grok (SuperGrok or X Premium+) |
Credentials connect once on any Device and reach every paired Device as the encrypted `credentials` blob. A bot runs with them on whichever Runner it is assigned to.
## License
GPL-3.0.
## Next
Prerequisites, install command, first run, and recovery.
Shortest path from install to a first successful invocation.
Processes, identity layers, pairing, and data flow.
Commands, flags, and `lorca serve` behavior.
Relay API, storage backends, and zero-knowledge surface.
Next: open [Installation](/installation) and run `bun run dev` (about one command; relay comes up on `0.0.0.0:8787`).