JellyfishBot
Developer Guide · 12

Tauri Desktop Launcher

12.1 Architecture

  • Tauri v2 (Rust + WebView) packaged as native desktop application
  • Bundles Python 3.12.7 + Node.js 20.18.0 + backend code + frontend build output
  • Users double-click .dmg / .exe to start — no command line needed

12.2 File Structure

text
tauri-launcher/
├── package.json                 # @tauri-apps/cli
├── dist/
│   └── index.html               # Self-contained launcher UI (inline CSS + JS + base64 logo)
├── bundle-resources/            # Staging area: app/, config/, frontend dist, launcher.py
├── scripts/
│   ├── build.py                 # One-click packaging
│   └── version.py               # Version management
└── src-tauri/
    ├── Cargo.toml               # tauri 2 / reqwest / tokio / serde / open / libc
    ├── tauri.conf.json          # Window 720×580, NSIS (Windows), macOS ≥10.15
    ├── build.rs
    └── src/
        ├── main.rs              # Entry point
        └── lib.rs               # 14 Tauri Commands

12.3 14 Tauri Commands

Core (9):

  • detect_environment — Python/Node.js/project file detection
  • load_env_config / save_env_config — read/write .env (preserves comments + unknown keys)
  • test_api_key — HTTP test OpenAI/Anthropic/Tavily connectivity
  • start_jellyfish — calls launcher.py --skip-check
  • stop_jellyfish — SIGTERM (Unix) / kill (Windows)
  • get_status — polls process + port liveness
  • open_in_browser — opens browser to frontend

Registration Codes / User Management:

  • list_registration_keys / generate_registration_keys(count) / delete_registration_key
  • list_admin_users / reset_admin_password / delete_admin_user / get_admin_stats

About / Tools (2026-04-20):

  • open_project_dir / open_users_dir / open_logs_dir — lazy-create then open
  • open_release_page — browser navigates to fixed URL
  • get_app_version — returns env!("CARGO_PKG_VERSION")

12.4 UI Structure (dist/index.html)

  • Left 76px narrow navbar (Logo + 4 page tabs)
  • Page 1 Console: 3-column environment detection pills + circular START button + API Keys config form
  • Page 2 Registration Code Management: table + generate/delete + copy button
  • Page 3 Account Management: stats summary 4 cards + user table + reset password/delete
  • Page 4 About / Tools: gradient version number + 4 tool cards (project dir / user data / log dir / Release)

Entire page is single-file HTML (inline CSS + inline JS + base64 logo) — no build step. When window.__TAURI__ is absent, uses mockInvoke(), so opening file://.../dist/index.html in browser also previews styling.

12.5 Key Gotchas

12.5.1 Windows \\?\ Extended Long Path Prefix (Critical Bug 2026-04-20)

  • Symptom: Windows .exe startup — uvicorn reports OSError: Cannot load native module 'Crypto.Util._cpuid_c' but .pyd file physically exists
  • Root cause: Tauri's app.path().resource_dir() on Windows returns extended long path prefix form like \\?\D:\JellyfishBot\; this prefix contaminates Python subprocess sys.executable; pycryptodome's os.path.isfile() cannot find sibling .pyd under \\?\ prefixed paths
  • Fix: src-tauri/src/lib.rs's strip_win_extended_prefix() helper, forcibly strips prefix in three places: resolve_project_dir / find_bundled_python / find_bundled_node; launcher.py adds _strip_extended_prefix() as double defense
  • Scope: affects numpy / scipy / matplotlib and all packages with native extensions
  • macOS completely unaffected

12.5.2 Other Gotchas

  • withGlobalTauri: true — Required! Otherwise window.__TAURI__ is undefined
  • server.js uses ESM — package.json has "type": "module"
  • Express 5 wildcards — use '/{*path}' instead of '*'
  • Paths must be absolute — launcher.py::_resolve_python/node() must return os.path.abspath()
  • macOS signing — after modifying Resources, need codesign --force --deep --sign - <app_path>

12.6 Windows Native Dev Environment

npx tauri dev / build both require:

  1. Rust toolchain (cargo in C:\Users\{user}\.cargo\bin\ — not in PATH by default)
  2. MSVC linker (link.exe) — VS 2022 Build Tools or Community
  3. Windows SDK (kernel32.lib / ntdll.lib) — easily missed when installing VS!
  4. Solution: VS Installer → Modify → check "Desktop development with C++"

One-liner to start dev:

powershell
$vsBat = "C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\VsDevCmd.bat"
& cmd /c "`"$vsBat`" -arch=x64 -no_logo && set" | ForEach-Object {
  if ($_ -match '^([^=]+)=(.*)$') { [Environment]::SetEnvironmentVariable($matches[1], $matches[2], 'Process') }
}
$env:Path = "C:\Users\$env:USERNAME\.cargo\bin;$env:Path"
cd tauri-launcher; npx tauri dev

Don't keep devUrl in tauri.conf.json: static project has no Vite/dev server, keeping it will cause tauri dev to hang waiting. Cold-start full Rust compilation ~4 minutes (457 crates), subsequent incremental ~5-30 seconds.

12.7 Iteration Rules

Changed FileHandling
dist/index.htmlCtrl+R in dev mode takes effect immediately; production requires npx tauri build
lib.rs / tauri.conf.jsonMust npx tauri build
launcher.py / server.js / app/** / frontend/dist/**Tauri resources, hot-patchable: directly overwrite corresponding files in install directory + restart launcher (macOS also needs codesign)

12.8 Building & Releasing

bash
cd tauri-launcher
python scripts/version.py bump patch     # Bump version
python scripts/build.py                  # Full packaging
python scripts/version.py tag --push     # Push tag → CI auto-build

CI/CD: .github/workflows/release.yml

  • Trigger: push tag v* or manual workflow_dispatch
  • Three-platform matrix: macOS-arm64 / macOS-x64 / Windows-x64
  • Artifacts uploaded + GitHub Release auto-created (draft)

Package size: DMG ~247 MB, extracted ~998 MB.

Previous←API ReferenceNextCross-platform Launcher (launcher.py)→