Development Guide

Quick Start

Get SUZENT running in development mode in under 2 minutes.

| Desktop app | Native window | Yes | python src/suzent/server.py AND cd src-tauri && npm run dev |

Note: Simply run suzent start to launch the full development environment.

Prerequisites

Required for All Development

• Node.js 20.x or higher
• Python 3.12 or higher

Required for Desktop App Mode

• Rust 1.75 or higher

  # Windows
  winget install --id Rustlang.Rustup
  
  # Or download from https://rustup.rs/

Platform-Specific Requirements

Windows

• Microsoft Visual C++ Build Tools
• WebView2 Runtime (usually pre-installed on Windows 10/11)

macOS

xcode-select --install

Linux (Ubuntu/Debian)

sudo apt-get update
sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.0-dev \
  libappindicator3-dev librsvg2-dev patchelf

Development Modes

Desktop App Mode

Uses Tauri to create a native desktop window. Requires Rust.

Terminal 1 - Start Python backend:

python src/suzent/server.py

Expected output:

INFO:     Starting Suzent server on http://127.0.0.1:25314
INFO:     Application startup complete.

Terminal 2 - Start Tauri:

cd src-tauri
npm install
npm run dev

This will:

1. Start Vite dev server (frontend)
2. Compile the Rust code (first time only, takes a few minutes)
3. Open a native desktop window
4. Frontend connects to backend

Local Ports

Default local endpoints for development:

• Backend API: http://127.0.0.1:25314
• Frontend dev server: http://127.0.0.1:18080

To avoid Windows reserved-port conflicts, frontend port values are sourced from:

• frontend/vite.config.ts (server.port)
• src-tauri/tauri.conf.json (build.devUrl)

Configuration

Development vs Production

Config File	Mode	Backend
tauri.conf.json	Development	External (port 25314)
tauri.conf.prod.json	Production	Bundled Python + uv venv

Development mode (npm run dev):

• No bundled backend - expects backend running on the local API endpoint
• Frontend hot-reload enabled
• DevTools available (right-click in window)

Production mode (npm run build):

• Bundles Python runtime + uv + suzent wheel as resources
• Creates venv on first launch, then auto-starts backend on dynamic port
• All assets bundled into single installer

Environment Variables

The backend automatically detects bundled environment through:

Variable	Purpose
SUZENT_PORT	Dynamically assigned port (0 = OS picks)
SUZENT_HOST	Bound to 127.0.0.1 in production
SUZENT_DATA_DIR	User data directory (defaults to ~/.suzent)
CHATS_DB_PATH	SQLite database path
LANCEDB_URI	LanceDB vector store path
SANDBOX_DATA_PATH	Sandbox data directory
SKILLS_DIR	Advanced extra skills directory override

Tauri Configuration

Edit src-tauri/tauri.conf.json to customize:

• Window size and behavior
• Application name and version
• Bundle settings
• Security policies

Hot Reload Behavior

Component	Hot reload	Action on change
Frontend (React)	Yes	Automatic
Backend (Python)	No	Restart manually
Rust code	No	Restart Tauri

Command Reference

Task	Command
Start backend	python src/suzent/server.py
Start Tauri dev	cd src-tauri && npm run dev
Bundle Python backend	python scripts/bundle_python.py
Build full app	cd src-tauri && npm run build:full
Build Tauri only	cd src-tauri && npm run build

Troubleshooting

Backend Issues

"resource path doesn't exist" during npm run dev

This is expected. Development mode does not use the bundled backend. Start the Python backend manually:

python src/suzent/server.py

Backend not responding

Verify backend is running:

curl http://localhost:25314/config

Should return JSON configuration.

Rust/Tauri Issues

"cargo: command not found"

Install Rust from https://rustup.rs/ and restart your terminal.

Cargo build fails

Update Rust and clean the build:

rustup update
cd src-tauri && cargo clean

Frontend Issues

Frontend shows connection errors

1. Verify backend is running: curl http://localhost:25314/config
2. Check browser console for the actual error
3. Ensure CORS is working (should be by default)

Changes not appearing

• Frontend changes: Should auto-reload. Try hard refresh (Ctrl+Shift+R).
• Backend changes: Restart the backend (Ctrl+C, then restart).
• Rust changes: Restart Tauri dev server.

General Issues

First build is very slow

The first Rust build takes 5-10 minutes to compile all dependencies. Subsequent builds are faster due to caching.

---

---

Production Build

Build the complete standalone application:

cd src-tauri
npm run build:full

This automatically bundles the Python runtime, uv, and suzent wheel, then builds the Tauri application.

Convenience scripts:

# Windows
.\scripts\build_tauri.ps1

# macOS / Linux
./scripts/build_tauri.sh

Build Artifacts

Platform	Location
Windows	src-tauri/target/release/bundle/msi/SUZENT_x.x.x_x64_en-US.msi
macOS	src-tauri/target/release/bundle/dmg/SUZENT_x.x.x_x64.dmg
Linux	src-tauri/target/release/bundle/appimage/suzent_x.x.x_amd64.AppImage

---

Desktop App Architecture

+-------------------------------------------+
|           Tauri Application               |
|  +--------------+    +------------------+ |
|  |   Webview    |    |  Rust Process    | |
|  |   (React)    |    |  - Backend       | |
|  |  Frontend    |--->|    Lifecycle     | |
|  |  Built       |    |  - Port Mgmt     | |
|  |  Assets      |    |  - First-Run     | |
|  +--------------+    |    Setup         | |
|         |            +------------------+ |
|         +-----HTTP API------+             |
|             (localhost:dynamic)           |
+-------------------------------------------+
                    |
            +-------v--------+
            | Python Backend |
            | (uv-managed    |
            |  venv)         |
            +----------------+

---

First-Run Behavior

When the desktop app launches for the first time (or after an update):

1. Venv Creation (~10–30 seconds): Rust runs uv venv with bundled Python, then installs the suzent wheel. A version marker prevents re-running on subsequent launches.
2. Playwright Install (~1–2 minutes): Chromium is downloaded for the browsing tool. Non-fatal — retries on first use if it fails.
3. Config Sync: Example configs and skills are copied to the app data directory. Existing files are preserved.

---

Application Data Location

Platform	Location
Windows	%APPDATA%\com.suzent.app\
macOS	~/Library/Application Support/com.suzent.app/
Linux	~/.config/com.suzent.app/

Contents: backend-venv/, chats.db, memory/, skills/, sandbox-data/, config/

---

Additional Troubleshooting

Bundle script fails — missing build package:

uv pip install build

Backend fails to start in built app:

• Check ~/suzent_startup.log for startup logs
• Delete backend-venv/ in the app data directory to force venv re-creation on next launch

Large bundle size — The bundled app is 80–150 MB (Python runtime, uv, LanceDB). Playwright/Chromium (~300 MB) is downloaded separately on first launch.