This page has two parts: installing/upgrading for end users, and running, checking and packaging from source for developers. If you only want to use the app, read "End-user installation".
End-user installation
Windows
Two options:
- Microsoft Store (recommended): open https://apps.microsoft.com/detail/9MV82J9G95GS and click Get. The Store installs it and keeps it updated, no administrator rights needed.
- NSIS installer: open Latest release, download
Rabbit-Chat-Studio-Windows-x64-setup.exeand follow the wizard.
The Store build is an MSIX package: its app config is redirected to
%LOCALAPPDATA%\Packages\XLBBB.RabbitChatStudio\LocalCache\..., not shared with the NSIS build; the.datafolder inside your workspace is shared. Releases ship the NSIS-setup.exeonly — no.msi(a localnpm run tauri buildstill produces one, for your own use). The Store build also skips the in-app GitHub update check: updates arrive through the Store.
Package managers (not available yet): the winget, Homebrew and Scoop manifests are not published, so winget install / brew install --cask / scoop install cannot find the package — use the two options above.
macOS
- Apple Silicon:
Rabbit-Chat-Studio-macOS-Apple-Silicon.dmg - Intel:
Rabbit-Chat-Studio-macOS-Intel.dmg
Open the .dmg and drag the app into Applications. Builds are ad-hoc signed, so the first launch requires right-click → Open, or System Settings → Privacy & Security → Open Anyway.
Linux
-
Universal:
Rabbit-Chat-Studio-Linux-x86_64.AppImagechmod +x Rabbit-Chat-Studio-Linux-x86_64.AppImage ./Rabbit-Chat-Studio-Linux-x86_64.AppImage -
Debian/Ubuntu:
.deb,sudo apt install ./Rabbit-Chat-Studio-*.deb -
Fedora/RHEL:
.rpm,sudo rpm -i Rabbit-Chat-Studio-*.rpm
Upgrading
Installed builds check the latest published GitHub Release on startup and show a banner when a newer version exists. You can also check manually under Settings → About & Updates. See Updates.
Run from source
Requirements
| Dependency | Version / notes |
|---|---|
| Node.js | 20.19+ or 22.12+ |
| Rust | stable, preferably installed via rustup |
| Tauri CLI | 2.x |
| Python 3 | only for docs/gen.py (the architecture page) |
| Windows | MSVC toolchain (Visual Studio Build Tools with Desktop development with C++) |
| macOS | Xcode Command Line Tools |
| Linux | Tauri 2 WebKitGTK dependencies, see below |
On Debian/Ubuntu:
sudo apt update
sudo apt install -y build-essential curl wget file libssl-dev \
libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev
Install dependencies
npm install
cargo install tauri-cli --version "^2"
Development mode
npm run tauri dev
This starts Vite on fixed port 1420 (strictPort: true), compiles the Rust side and launches Tauri. Closing the app also stops Vite.
Frontend only:
npm run dev
Then open http://localhost:1420. In a plain browser there is no Tauri IPC, so file dialogs, window controls, MCP and similar features do not work.
Checks and tests
# Frontend type check
npx tsc --noEmit
# Frontend production build (does not require a git tag)
npx vite build
# Rust check
cargo check --manifest-path src-tauri/Cargo.toml
# Rust unit tests (tools module: dispatcher, todos, timer, …)
cargo test --manifest-path src-tauri/Cargo.toml
When changing UI, check both light and dark themes and prefers-reduced-motion. The visual spec is DESIGN.md: colors, radii, shadows and motion must use the tokens in src/App.css.
Documentation and the website
The published site in docs/site/ is plain static files; two generated pages are built from sources in the repository and are not committed (see .gitignore):
# Architecture page → docs/site/architecture.html
python3 docs/gen.py
# Wiki pages → docs/site/wiki/** from docs/wiki/{zh,en}/*.md
node scripts/gen-wiki.mjs
gen-wiki.mjs needs markdown-it (a regular dependency, so npm install is enough) and fails the build on a broken internal link.
China / restricted networks: Cargo mirror
If Cargo cannot fetch dependencies, override the source:
cargo check --manifest-path src-tauri/Cargo.toml \
--config 'source.crates-io.replace-with="rsproxy-sparse"' \
--config 'source.rsproxy-sparse.registry="sparse+https://rsproxy.cn/index/"'
The checked-in .cargo/config.toml may point at the USTC mirror; CI deletes it because GitHub runners cannot reach it.
Production build
npm run tauri build
Artifacts:
src-tauri/target/release/bundle/
| Platform | Bundles |
|---|---|
| Windows | .msi, NSIS -setup.exe |
| macOS | .app, .dmg (current architecture) |
| Linux | .AppImage, .deb, .rpm |
Important: a git tag is required
npm run build (and the beforeBuildCommand of tauri build) runs sync-version:git-tag, which reads the newest git tag and writes it to:
package.jsonsrc-tauri/Cargo.tomlsrc-tauri/tauri.conf.json
Without a tag, the build fails. Create one first:
git tag v2.1.1
git push origin v2.1.1
Or set the version manually:
node scripts/sync-version.cjs --version 2.1.1
Other version-sync commands:
node scripts/sync-version.cjs --from-git-tag
node scripts/sync-version.cjs --bump patch
npm run sync-version:git-tag
npm run sync-version:bump-patch
To verify frontend styles only, use
npx tsc --noEmit && npx vite build, notnpm run build.
Microsoft Store (MSIX) bundle
The Store package is built on Windows only, because it uses the Windows SDK makeappx:
npm run msix
scripts/build-msix.ps1packages the NSIS payload intosrc-tauri/msix/, a full-trust Desktop Bridge manifest whose Partner Center identity lives instore.config.json(XLBBB.RabbitChatStudio), and writes the four-part MSIX version.- Pass
-DevCertto sign with a local development certificate; real submissions are signed by the Store. - Store installs are detected by their
WindowsAppspath, which is why the in-app updater stays out of the way there. - CI builds the
.msixin the Windows job and keeps it as an Actions artifact only — it is not attached to the GitHub Release. - Policy mapping, certification notes and screenshots live in
docs/store-publishing.mdanddocs/store/.
GitHub Actions release
.github/workflows/release.yml is triggered by:
- pushing a
v*tag; - or manual
workflow_dispatch(build only, no release; useful as a smoke test).
git tag v2.1.1
git push origin v2.1.1
The workflow builds on 4 runners:
| Runner | Target |
|---|---|
macos-latest |
aarch64-apple-darwin |
macos-latest |
x86_64-apple-darwin |
ubuntu-22.04 |
Linux x86_64 |
windows-latest |
Windows x64 |
Behavior:
- The tag drives the version: the workflow fails fast if the pushed tag is not the newest tag.
- The release is a draft until published by hand:
releaseDraft: true; assets from all four platforms upload while the Release stays invisible, then a maintainer publishes it on the Releases page. - macOS is ad-hoc signed:
APPLE_SIGNING_IDENTITY='-'; replace with real signing/notarization secrets for distribution. - The MSIX is an artifact, not a release asset: see above.
- winget submission (inactive):
.github/workflows/winget.ymlis kept, but the package is not accepted intomicrosoft/winget-pkgsyet; it submits only afterWINGET_TOKENand a fork exist. - CI does not use the China mirror: the workflow runs
rm -f .cargo/config.toml. - Drafts are invisible to the update check:
GET /releasesnever returns drafts.
The Pages workflow (.github/workflows/pages.yml) is separate: it regenerates architecture.html and the wiki pages and publishes docs/site/ — see Development and Architecture.
Build troubleshooting
| Symptom | Cause / fix |
|---|---|
npm run build says no git tag |
Create a tag first, or use npx vite build for the frontend only |
tauri dev fails because the port is busy |
Vite uses fixed 1420 with strictPort; free the port |
| Windows linker errors | Install MSVC Build Tools and use x86_64-pc-windows-msvc, not GNU |
| Missing WebView2 | Install the Edge WebView2 Runtime |
Linux cannot find webkit2gtk-4.1 |
Install the Tauri 2 WebKitGTK dependencies |
| macOS blocks the first launch | Right-click → Open, or allow it in Privacy & Security |
| Cargo fetch timeouts | Use the rsproxy override or configure a proxy |
| Versions are inconsistent | Run node scripts/sync-version.cjs --from-git-tag |
npm run msix cannot find makeappx |
Install the Windows SDK signing tools; the Store bundle builds on Windows only |
gen-wiki.mjs reports a broken link |
The target page or anchor in docs/wiki/ does not exist — fix the markdown, then re-run |
License
Rabbit Chat Studio is MIT licensed (it moved from GPL-2.0-only in v3.2.0); see LICENSE.