Getting Started: The Desktop App
For: people who want a window onto their palace: a native dashboard, the instruments the palace generates for itself, and an optional companion chat. Setup time: about 15 minutes if Node and Rust are already installed. What you need: Git, Node.js 18+, a Rust toolchain (1.70+) with the wasm32-unknown-unknown target, and trunk. Optional: Ollama, if you want local chat.
Naming update
Earlier versions of these docs described three product tiers (Scholar, Wizard, LLMAGE). That naming is retired. loci is one plain-text substrate with three run modes: plain markdown, a desktop app, and a CLI. All three shipped together as the 0.6 open beta (v0.6.0-beta). This page covers the desktop app. The word "wizard" survives only as the title of the app's setup screen.
What the desktop app is
The desktop app (Tauri, v0.6.0-beta) is the cockpit view of a loci palace. It is one of the two expressions built on top of the plain-markdown substrate (the CLI is the other). It is not the substrate, and you do not need it to start.
| Run mode | What it is |
|---|---|
| Plain markdown | The door. Copy the templates/ kit, point any file-aware AI at your palace CLAUDE.md. No build. See the plain markdown setup. |
| Desktop app | The cockpit (Tauri, v0.6.0-beta). A native Operations dashboard plus a tab per instrument your palace generates for itself. This page. |
| CLI | loci-cli (Rust, v0.6.0-beta). A small read-only binary that prints your palace from the terminal. See the CLI guide. |
If you have not built a palace yet, start in plain markdown first. The app opens a palace; it does not replace one (though it can scaffold a minimal one for you, see below).
Requirements
| Requirement | Details |
|---|---|
| Git | To clone the repo |
| Node.js | 18+ |
| Rust | Stable toolchain, 1.70+. The Tauri CLI installs via npm install. |
wasm32-unknown-unknown target | The frontend is a Leptos/WASM app; add the target with rustup target add wasm32-unknown-unknown. |
trunk | Builds the WASM frontend. Not an npm package: install with cargo install trunk. |
| Ollama (optional) | Only if you want the local companion chat |
No browser extension. No account. No API key.
Install and run
The app has two halves: a Rust/Tauri shell and a Leptos/WASM frontend (desktop/src-leptos). Tauri drives trunk for you, but trunk and the WASM target have to be installed first:
git clone https://github.com/huximaxi/loci
cd loci/desktop
rustup target add wasm32-unknown-unknown
cargo install trunk
npm install
npm run tauri:devnpm run tauri:dev runs trunk serve for the frontend under the hood; npm run tauri:build runs trunk build --release the same way. Skipping the rustup or cargo install step fails at trunk: command not found.
For a production bundle:
npm run tauri:buildThe bundle lands under src-tauri/target/release/bundle/. For build troubleshooting, see the repo's main SETUP-GUIDE.md, not desktop/QUICKSTART.md (that file describes an older, different onboarding flow and is out of date).
First run
The setup screen (titled "loci wizard") offers two doors:
- Open a palace I keep. Point the app at your palace folder: a directory with a
PALACE.mdorCLAUDE.mdat its root. Both supported layouts resolve (see below). - Start a new one. Pick a parent folder and run the naming ceremony: a short interview that names your companion and scaffolds a minimal palace. If no local model is installed you can choose to start without AI; the palace scaffolds anyway and the inference features wait until you finish onboarding later.
There is no tier selection and nothing is uploaded anywhere. The palace stays a folder of markdown on your disk.
The cockpit
Four surfaces.
Operations
The native dashboard. When your palace ships no instruments, this is the whole view and it renders the app's own tables. When instruments exist, a tab strip appears and Operations keeps the header while each list gets one owner: if an instrument renders your job table, Operations does not repeat it.
Instrument tabs
An instrument is a self-contained page a palace generates for itself: a map, a watcher, a ledger. Concretely, a standalone .html file with its live data embedded as JSON in a <script id="payload"> or <script id="snapshot"> block.
The app discovers instruments by convention, never by configuration. It scans four places, non-recursively: the palace root, _palace/, cockpit/, and _palace/cockpit/. One tab per instrument found; dashboard.html is skipped (that is a palace's own generated cockpit page, and a cockpit inside the cockpit helps no one). Tabs carry an entry-count badge when the embedded payload allows one. Files are read through a path-validated command; traversal and absolute paths are rejected.
Tool shelf (gate ledger)
If your palace keeps a tools ledger (tools.items in palace-map.json or map.json), the shelf renders one card per external tool with its quarantine verdict: admitted, admitted-escorted, deferred, held-conditional, or rejected. The shelf lists; it never loads or runs anything. A palace without a ledger gets an empty shelf, never an error.
Settings
A dedicated Settings view, separate from Operations and the instrument tabs. This is where the two companion-chat brains (see below) show their connection state, and where the "check" control under updates lives: it runs the same read-only palace-methodology comparison as PALACE-UPDATE.md (reads your palace's version anchor, compares it to the published methodology, reports the delta), on demand, nothing applied. There is no separate app-binary version check; this is the one update mechanism, and it checks your palace's methodology, not the app itself.
The companion chat (optional)
The app can run a chat with your companion. Two brains, both explicit:
- Local. Talks to Ollama (or any local server with an OpenAI-compatible endpoint) on this machine. Endpoint URLs are validated to localhost or Tailscale addresses. Fail-closed: an error is an error, never a silent fallback to an external service.
- Online (opt-in). Shells out to the Claude Code CLI under your own existing login. External by definition, so it is only ever enabled by an explicit, marked opt-in, never as a fallback.
The app stores no API keys: the local brain needs none, and the online brain uses the CLI's own authentication. Settings shows the state of both. For the local brain, install Ollama and pull a model (for example ollama pull llama3.2). The app works fine with neither: the cockpit reads your palace regardless.
Supported palace layouts
Two palace shapes work, matched by both the app and the CLI:
- rooms inside
_palace/: the original loci layout - rooms at root: palaces ported from older organic structures
Either resolves; you do not need to restructure an existing palace. Palace files stay plain markdown: crystals, handovers, and garden files are ordinary .md you can read in any editor. Deleting the app leaves the palace intact.
What is not in the app
Not in v0.6.0-beta
Older drafts of these docs described features that do not exist in the shipped beta:
- No tiers to select or unlock
- No chronicle or automatic session log: continuity is handovers, written when you ask for the session delta
- No
.crystalor.plantfile formats: crystals and garden files are plain markdown - No Chrome extension
- No
@loci ...chat-style invocation, and noloci mcpcommand in the CLI - No cockpit button for the MCP server: the app ships an MCP server (tools named
create_locusandtag_locus, plus a search resource) that starts and stops through Tauri commands, but nothing in the interface surfaces it yet. Reaching it today means calling those commands directly, not clicking anything in the cockpit.
If a document tells you to configure loci mcp or invoke @loci, it is describing a draft that never shipped.
Next steps
- No palace yet? Start with the plain markdown setup
- Prefer the terminal? See the CLI guide
- Keep an existing palace current: say "update my palace" to your AI, or use the "check" control under Settings → updates. Both run the same read-only protocol,
PALACE-UPDATE.mdin the repo: it walks your palace content forward against the published methodology, nothing applied without consent - See the changelog for everything that shipped in v0.6.0-beta