User Guide · 01

Quick Start

1.1 Three Launch Methods

Method	Audience	Advantages
Desktop App (Tauri)	Non-technical end users	Double-click to start, bundled runtime, auto-managed
Command Line	Developers	Hot reload, free debugging
Docker	Team / server deployment	One-click deploy, production-stable

1.2 Desktop App (Recommended for New Users)

Download the installer for your platform from GitHub Release:
- Windows: JellyfishBot-x.y.z-x64.exe (NSIS installer)
- macOS (Apple Silicon): JellyfishBot-x.y.z-aarch64.dmg
- macOS (Intel): JellyfishBot-x.y.z-x64.dmg
Install and open JellyfishBot.
First launch automatically:
- Detects bundled Python 3.12 + Node.js 20 runtime
- Extracts backend / frontend resources to install directory
On the Console tab, enter at least one LLM API Key (OpenAI or Anthropic) and click Test Connection to verify.
Click the central circular START button to launch backend services.
When ready, browser opens automatically at http://localhost:3000.

Desktop App 4 Tabs

Tab	Function
Console	Environment detection, API Keys config, START / STOP button
Registration Code Management	Generate, copy, delete registration codes (needed on first deploy)
Account Management	View user list, reset passwords, delete users, statistics
About / Tools	Version number, check latest Release, open project dir / user data / log dir

Closing the desktop app = stops backend services + cleans up child processes.

1.3 Command Line (Developers)

Prerequisites

Python 3.11+
Node.js 20+
At least one LLM API Key (Anthropic or OpenAI)
A valid registration code (run python generate_keys.py on first deploy to generate)

Recommended: Cross-platform Launcher

bash

# One-click start (auto port detection + old instance cleanup + dual-process management)
python launcher.py              # Production mode
python launcher.py --dev        # Dev mode (uvicorn --reload + vite dev)
python launcher.py --port 9000  # Custom backend port
python launcher.py --backend-only  # Backend only

# Shortcut scripts
./start_local.sh    # Mac/Linux
start_local.bat     # Windows (double-click)

Open http://localhost:3000 in browser after startup.

Manual Start (for debugging)

bash

# 1. Backend
python -m venv venv
venv\Scripts\activate          # Windows
source venv/bin/activate       # Linux/macOS
pip install -r requirements.txt
cp .env.example .env
# Edit .env, fill in API Key
python generate_keys.py        # Generate registration codes (first time)
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# 2. Frontend (new terminal)
cd frontend
npm install
npm run dev                    # → http://localhost:3000

1.4 Docker Deployment (Team/Server)

bash

# 1. Prepare config
cp .env.example .env
# Edit .env, fill in API Key, etc.

# 2. Generate registration codes
python generate_keys.py
# Or use the "Registration Code Management" tab in the Tauri Desktop App

# 3. Build and start
docker compose up -d --build

# 4. View logs
docker compose logs -f
docker compose logs -f jellyfishbot   # App logs only
docker compose logs -f nginx          # Nginx logs only

Architecture

text

Cloudflare (SSL) → Nginx (:80) → Express (:3000) → FastAPI (:8000)

Data Persistence

yaml

volumes:
  - ./data/users:/app/users    # User data: conversations, files, checkpoints, API Keys

Health Check

Container has built-in health check (checks FastAPI /docs). Nginx only accepts traffic after backend is ready.

NextLogin & Registration→