overview getting started

Getting started

This page covers the local setup path for the web app, desktop app, and validation suite. The command list is based on README.md, AGENTS.md, Cargo.toml, frontend/package.json, and src-tauri/tauri.conf.json.

Prerequisites

Tool	Why it is needed
Rust 1.85 or newer	The root crate in Cargo.toml uses edition 2024.
Node.js 22 and npm	CI uses Node 22 in .github/workflows/ci.yml; frontend scripts live in frontend/package.json.
Tauri CLI 2	Desktop development and packaging use Tauri 2 from src-tauri/Cargo.toml and src-tauri/tauri.conf.json.
WebKitGTK 4.1 on Linux	Tauri Linux builds install libwebkit2gtk-4.1-dev in .github/workflows/ci.yml.

Install the Tauri CLI when you need desktop development:

cargo install tauri-cli --locked --version "^2"

Install frontend dependencies

cd frontend
npm install
cd ..

CI uses npm ci, but local development can use npm install after cloning.

Run the local web app

src/main.rs serves the built frontend from frontend/dist, so build the frontend before running the Rust server.

cd frontend && npm run build
cd ..
cargo run

Open http://127.0.0.1:3001. The server resolves frontend/dist in src/api/app.rs through frontend_dist_path().

For frontend-only UI work, run the Vite dev server:

cd frontend
npm run dev

Run the desktop app

The Tauri config in src-tauri/tauri.conf.json runs cd frontend && npm run dev before desktop dev mode.

cargo tauri dev

Production desktop bundles use the Tauri build command from README.md:

cd src-tauri
cargo tauri build

Validation commands

The root agent guidance in AGENTS.md defines the main gates:

cargo fmt --check
cargo test
cargo clippy -- -D warnings

Run Tauri wrapper checks from src-tauri/:

cd src-tauri
cargo test
cargo fmt --check
cargo clippy -- -D warnings

Run frontend checks from frontend/:

cd frontend
npm test
npm run lint
npm run build

CI currently gates on frontend build for production, but the Vitest suite is present and runs in .github/workflows/ci.yml for frontend changes.

Release metadata check

Release metadata must stay aligned across Rust, Tauri, and frontend manifests. Use scripts/check_release_metadata.py:

python3 scripts/check_release_metadata.py
python3 scripts/check_release_metadata.py --expected-tag v2.1.95

See deployment and tooling for the release and packaging automation.

Key source files

File	Purpose
README.md	End-user setup, quick start, and install notes.
AGENTS.md	Repository-specific validation and coding guidance.
Cargo.toml	Root Rust crate and local web binary metadata.
frontend/package.json	Frontend scripts and dependencies.
src-tauri/tauri.conf.json	Tauri dev, build, bundle, and security settings.
.github/workflows/ci.yml	CI commands and path filters.