Kai

Kai is a local-first desktop assistant for macOS, Windows, and Linux. It combines private on-device inference with reminders, recurring Automata, voice notes, web search, and optional account-connected services such as Gmail and Google Calendar.

The desktop app works without an account for local chat and one-time reminders. Signing in enables account-owned Automata, connected services, and optional hosted models while leaving the local model and local conversation store under the user's control.

Production website: kai.thesolenoid.space

For downloads and the safe way through early-build operating-system warnings, see the installation guide.

Download

Alternative packages: Windows .msi, Debian/Ubuntu .deb, and Fedora/RHEL .rpm.

Not sure which package to choose? Use the platform-aware download page. Early builds may trigger an operating-system warning; follow the illustrated installation guide without disabling system-wide protections.

What Kai does

• Chats through a local Gemma model downloaded after installation.
• Creates one-time reminders and delivers them through the native app.
• Runs account-owned Automata such as morning briefings, verses, quotes, or creative prompts after sign-in.
• Records and transcribes voice notes through the same action pipeline as typed messages.
• Searches the public web through a keyless DuckDuckGo integration.
• Connects multiple Gmail and Google Calendar sources with explicit read-only consent.
• Supports local and remote MCP tools with confirmation gates for sensitive operations.
• Offers optional OpenAI-compatible hosted inference without changing the chat interface.

Product boundaries

Kai is local-first, not offline-only.

Capability	Where it runs	Network use
Local chat	Desktop	None after the model is downloaded
Conversations, reminders, preferences	Desktop	None
Recurring Automata	Desktop, account-owned	Account required; connected tools use their providers
Public web search	Desktop	DuckDuckGo or Wikipedia
Gmail and Calendar	Desktop to Google	Only after account connection and consent
Hosted models	Website gateway	Optional and visibly marked as hosted
Account linking	Website gateway	Optional

Models are not bundled in the installer. Kai probes the computer, recommends an appropriate model, then downloads its weights from Hugging Face into the operating system's app-data directory.

Architecture

Layer	Technology	Responsibility
Desktop shell	Tauri 2 and Rust	Native lifecycle, storage, tools, scheduling, audio, security
Desktop UI	React 19, TypeScript, Tailwind CSS 4	Chat, settings, activity, models, Automata
Local inference	llama.cpp / llama-server	OpenAI-compatible local model runtime
Website	Next.js 16 and React 19	Landing page, downloads, authentication, account dashboard
Gateway	Better Auth and Next.js route handlers	Device authorization, integrations, hosted inference
Database	PostgreSQL	Accounts, sessions, integrations, cloud usage

The desktop React application invokes Tauri commands and subscribes to scoped events. Rust owns the agent loop and does not accept a model's claim that an action succeeded: required reminders, mail reads, searches, and Automata changes must produce a real tool result before Kai confirms them.

See the architecture overview for the deeper runtime design and the cloud authentication contract for the desktop-to-website protocol. The documentation index links the complete set.

Repository layout

src/                         Desktop React application
src-tauri/src/               Rust application and agent runtime
src-tauri/src/agent/         Model/tool orchestration and approval flow
src-tauri/src/inference/     llama-server process supervision
src-tauri/src/models/        Model catalog, hardware probe, verified downloads
src-tauri/src/scheduler/     Reminders, recurring jobs, proactive runs
src-tauri/src/tools/         Built-in tools and combined tool registry
src-tauri/runtime/           Platform llama.cpp runtime, generated and gitignored
web/app/                     Next.js pages and API routes
web/lib/                     Authentication, integrations, releases, gateway services
web/db/                      Idempotent PostgreSQL migrations
scripts/                     Runtime and native-app build helpers
.github/workflows/           CI and cross-platform release automation

Requirements

• Node.js LTS
• pnpm 10
• Stable Rust toolchain
• Platform prerequisites from the Tauri 2 documentation
• PostgreSQL for website and account features

Linux development additionally needs WebKitGTK, AppIndicator, ALSA, and the standard Tauri packaging dependencies. GitHub Actions installs the exact Ubuntu packages used by CI and releases.

Desktop development

Install dependencies and fetch the platform-specific llama.cpp runtime:

pnpm install
pnpm runtime
pnpm tauri dev

pnpm runtime must run before a Tauri build. The runtime is a bundled sidecar; model weights remain separate and are downloaded in the app.

For macOS behaviour that depends on a stable bundle identity, including notifications and Keychain access, use:

pnpm app:verify

This builds, signs with an available development identity, launches the debug application bundle, and verifies that it remains running. To start the website and the signed desktop app together, use:

pnpm stack:run

The combined launcher keeps the local website on http://localhost:3100 for as long as Kai is open.

Website development

Create a local database and environment file:

createdb kai
cp web/.env.example web/.env.local
pnpm --dir web db:setup
pnpm --dir web dev

The site runs at http://localhost:3100. Point a development desktop build at it with:

KAI_CLOUD_GATEWAY_URL=http://localhost:3100 pnpm tauri dev

Minimum website variables:

DATABASE_URL
BETTER_AUTH_SECRET
BETTER_AUTH_URL

Production should also set a stable KAI_CREDENTIAL_ENCRYPTION_KEY. Google, GitHub, Resend, and hosted-inference variables are documented in web/.env.example.

Account and integration flow

1. The desktop asks the gateway for a device code.
2. Kai opens the website's /device page.
3. The signed-in user approves the code.
4. The desktop stores its account token in the operating system credential vault.
5. Connected integrations are listed without returning their stored credentials.
6. When a service is used, the gateway exchanges its stored grant for a short-lived provider token.
7. Tool traffic goes directly from the desktop to the provider.

Google sign-in and Google Workspace access are deliberately separate. Signing in identifies the account; connecting Gmail and Calendar requests an additional read-only consent grant. Multiple Google accounts can be attached to one Kai account.

Testing

Run the full local suite:

pnpm test
pnpm build
pnpm --dir web test
pnpm --dir web typecheck
pnpm --dir web build
cargo fmt --manifest-path src-tauri/Cargo.toml --check
cargo clippy --manifest-path src-tauri/Cargo.toml --all-targets -- -D warnings
cargo test --manifest-path src-tauri/Cargo.toml --lib

The check workflow runs the same desktop, website, formatting, Clippy, and Rust tests on every push to main and every pull request.

Releases

The release workflow builds these public desktop packages:

Runner	Target	Packages
macOS ARM	aarch64-apple-darwin	.app, .dmg
macOS Intel	x86_64-apple-darwin	.app, .dmg
Windows x64	x86_64-pc-windows-msvc	.msi, setup .exe
Linux x64	x86_64-unknown-linux-gnu	.AppImage, .deb, .rpm

Every production installer is compiled with KAI_CLOUD_GATEWAY_URL=https://kai.thesolenoid.space. The workflow validates the repository first, builds all four targets into one draft GitHub release, and publishes it only after every platform succeeds. The website reads the latest GitHub release and turns its assets into platform-specific download buttons.

To publish a version, update the version in package.json, web/package.json, src-tauri/Cargo.toml, and src-tauri/tauri.conf.json, then push a matching tag:

git tag v0.1.4
git push origin v0.1.4

The workflow can also be started manually; manual builds are marked as prereleases.

Signing

macOS distribution uses the Apple secrets already referenced in the release workflow:

APPLE_CERTIFICATE
APPLE_CERTIFICATE_PASSWORD
APPLE_SIGNING_IDENTITY
APPLE_ID
APPLE_PASSWORD
APPLE_TEAM_ID

Without them, GitHub ad-hoc signs the complete macOS app so its bundle remains internally valid, but users must still approve the app through Gatekeeper because it has no Developer ID or notarization ticket. Windows builds without a certificate and shows a SmartScreen warning. Configure production Apple notarization and Windows code signing before presenting the installers as trusted public builds.

Automatic updates are not currently enabled. TAURI_SIGNING_PRIVATE_KEY variables are reserved for a future Tauri updater rollout and are not the same as Apple or Windows platform signing.

Production website deployment

The production website is deployed from web/ on Vercel. It needs a managed PostgreSQL database and the environment variables listed in web/.env.example. After provisioning the database, run this once with the production DATABASE_URL:

pnpm --dir web db:setup

Set BETTER_AUTH_URL=https://kai.thesolenoid.space, register https://kai.thesolenoid.space/api/auth/callback/google with Google, and enable the Gmail and Google Calendar APIs before connecting Workspace sources.

Database migrations in web/db/ are idempotent and may be run again after a deployment introduces a new migration.

Optional hosted inference

Hosted models remain disabled unless KAI_INFERENCE_BASE_URL is configured. The upstream must expose an OpenAI-compatible chat-completions API. A single model can be configured with KAI_INFERENCE_MODEL, or multiple public models can be mapped through KAI_HOSTED_MODELS.

The public model identifier never lets a desktop client choose an arbitrary upstream URL. Usage is metered in PostgreSQL against KAI_MONTHLY_TOKEN_QUOTA.