Install

Prerequisites

• macOS 13+, Windows 10+ (the installer brings WebView2 if it is missing), or a Linux desktop with WebKitGTK 4.1 (Ubuntu 22.04+, Fedora 36+, Debian 12+ and their relatives).
• A supported CLI, a provider API key, or Ollama with a downloaded chat model.
• To build: Rust 1.80+, Node 20+; on Linux also libwebkit2gtk-4.1-dev, libappindicator3-dev, librsvg2-dev, patchelf and libgtk-3-dev.

For an installed app, choose My own API key in Settings and save a key for the provider you want. Keys live in the platform's secret store under the principia-desk service with separate <provider>_api_key accounts (the Keychain on macOS, the Credential Manager on Windows, the Secret Service on Linux); a key saved under the previous service name is still read, so an upgrade never looks like a lost key. A machine with no secret store answering, or a headless one, takes ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY (or GEMINI_API_KEY), OPENROUTER_API_KEY, GROQ_API_KEY, MISTRAL_API_KEY or DEEPSEEK_API_KEY from the environment instead, and those win over a stored key everywhere.

Build from source

git clone https://github.com/dark-matter08/principia-desk.git
cd principia-desk
npm install
npm run tauri dev           # against a dev server, hot reload
npm run tauri build         # the installers for this machine, under src-tauri/target/release/bundle/

--bundles app on macOS builds only the .app (cp -R "src-tauri/target/release/bundle/macos/Principia Desk.app" /Applications/); --bundles msi,nsis on Windows and --bundles deb,rpm,appimage on Linux pick the packages. Launch it, complete the setup (escape phrase and tutor check), add a class with a starting point and a study time, and it is armed.

Heads-up: the builds are unsigned for the operating system. On macOS the first launch is right-click → Open, or xattr -dr com.apple.quarantine "/Applications/Principia Desk.app"; on Windows, SmartScreen asks for More info → Run anyway; on Linux, chmod +x the AppImage. sudo apt install ./principia-desk_<v>_amd64.deb from your Downloads folder may end with a notice that the file "couldn't be accessed by user '_apt'": that is apt's sandbox talking about the download step it did not need, and the lines above it (Setting up principia-desk) are the install succeeding.

Releases

Every release carries installers for each platform, built by .github/workflows/release.yml when a version tag is pushed: Apple Silicon and Intel disk images, a Windows MSI and NSIS installer, and a Linux .deb, .rpm and AppImage. They are unsigned (see the heads-up above). To cut one, set the version everywhere it is written, note it in the changelog, tag and push:

npm run version:set -- 0.2.0
git commit -am "chore: release 0.2.0"
git tag v0.2.0 && git push origin main v0.2.0

The workflow verifies the tree first, refuses a tag that does not match the versions in package.json, tauri.conf.json and Cargo.toml, opens the release as a draft, attaches every platform's installers to it, and publishes it only once the updater manifest is written, so releases/latest never names a half-built release (creating the release in the GitHub interface pushes the tag and starts the same run). The release notes are the changelog's section for the version (scripts/release-notes.mjs). A shelved copy of the branch-binaries workflow sits in .github/workflows-shelved/ for trying installers from a branch before anything is tagged.

Updates from inside the desk

An installed desk (0.2.1 and later) reads the release's latest.json after it starts and every six hours, shows a newer version in Settings › Updates with the changelog notes, and installs it only when asked: the app bundle is replaced on macOS, the installer runs on Windows, the AppImage is swapped in place on Linux, and a .deb or .rpm goes through the package manager with a graphical password prompt. The desk relaunches after; the profile and its history stay where they are. This is not a publisher signature (the installers stay unsigned for the operating system): every installer gets a .sig from an Ed25519 key the pipeline holds as the TAURI_SIGNING_PRIVATE_KEY secret, tauri.conf.json carries the public half, and a download whose .sig does not verify is refused before anything runs, so a tampered file cannot ride in on an update. The last job of the release workflow writes the manifest from the assets the release actually carries. PRINCIPIA_NO_UPDATE_CHECK=1 keeps a desk from checking, for a managed machine.

Upgrading from System Design Roulette

The product carried its old identifiers for a while so a rename could not strand anyone's history. They have now moved with the name, and the first launch under the new identity brings the old profile across rather than starting you empty:

• The bundle identifier is com.darkmatter.principia-desk and the database is principia.db. If this build finds no profile of its own, it takes a consolidated copy of the one written under the old identifier, including anything still in its write-ahead log, and leaves the original untouched.
• The secret store service is principia-desk. Reads fall back to the old service, so saved provider keys keep working.
• The scheduler entry is com.darkmatter.principia-desk (the launch agent), principia-desk (the systemd timer) or Principia Desk (the scheduled task). The one installed under the old identity is unloaded and deleted on first launch, so a machine never carries two.
• The release token is principia-unlock, and a stick prepared with the old sdr-unlock name still frees a locked desk.

Numbered migrations still run after a pre-upgrade backup, and finished daily-routine sessions still import into the shared runtime once. See docs/STORAGE.md.