Skip to main content

​
Prerequisites

Running from source needs three things:

​
Install and run

1

Clone and install

This is a workspace repo, so a single install covers apps/*, apps/sidecar/*, packages/*, and plugins/*.
2

Start the desktop app

One command brings up three things: the Next dev server with hot reload, incremental Rust compilation, and the agent sidecar process. The first Rust build takes a while; everything after it is incremental.
3

Just the frontend, in a browser

Next only, no Tauri host. The sidecar falls back to local SQLite storage, which is handy for pure UI work.
4

Configure a model

Open Settings → Models inside the app and add a provider API key. Credentials go to the system keychain rather than to plaintext on disk. On macOS the service name is com.kova.assistant.

​
Common commands

​
Smoke test

You can exercise the sidecar without booting the Rust host:
Without the host it falls back to local SQLite storage, which makes this a good way to verify protocol handshake, tool registration, and session reads/writes in isolation.

​
Dev and release data stay separate

This one bites people, so it gets its own section. bun run tauri:dev layers apps/desktop/src-tauri/tauri.dev.conf.json on top, with the identifier com.kova.assistant.dev and the display name “扣瓦 Dev”. The app data directory therefore becomes:
Three consequences follow:
  • Installing or uninstalling the release build never touches dev data, and vice versa;
  • The dev build keeps its master key in master.dev.key inside the data directory (this avoids spurious key rotation when the keychain ACL refuses to read after a rebuild), while release builds use the system keychain. The two ciphertexts are mutually unreadable;
  • Because the ciphertexts differ, you re-enter credentials once when crossing environments.
The global ~/.kova/ layer is intentionally shared — it is a machine-level configuration layer outside the installer’s control, so isolation only happens at the Application Support layer.Also note that a bare cargo run that bypasses the CLI does not inject the dev config and will fall back to the release identifier.

​
Common issues

Panel HTML files and built-in plugin zips are build artifacts and are not committed. Run bun run build:plugins to generate the HTML, then cd apps/sidecar/pi-agent && bun run plugins:pack to repack the zips. build:sidecar, test, and smoke all fill in missing artifacts automatically.
This is expected. RN 0.86 can only pair with react 19.2.3, while desktop runs Next with react 19.3 — each keeps its own copy. The repo relies on install.hoistingLimits = "workspaces" to install mobile dependencies under apps/mobile/node_modules, preventing hoisting from raising either version.
This is a template repo, and rebranding is one command:
Windows uses scripts\rename.bat. It covers all three brand forms (slug / Pascal / UPPER), the internal pi-desktop id, the Tauri display name and bundle id, and .kova-plugin directory names — and backs everything up first.

Next

See what these capabilities look like in use.