Quick Start

v1.3.1 offers two model paths: an existing Codex / Cursor account, or DeepAgents with a model API key. The account-backed path supports daily admin chat and internal Services over web, API and Service WeChat. Chats using that connection need no separate LLM API key and use the account’s available models and quota.

The launcher includes Python and Node.js; install, sign in to and authorize your chosen CLI separately. Account-backed runtime currently requires a macOS / Linux backend. Windows installers retain the DeepAgents / API workflow. Start with 4.12 Codex / Cursor in the Chat chapter, then follow 6.6.7 in Settings to publish an internal Service.

1.1 Three Launch Methods

1.2 Desktop App (Recommended for New Users)

1. Download the installer for your platform from GitHub Release:
   • Windows: OpenJellyfish_x.y.z_x64-setup.exe (NSIS installer)
   • macOS (Apple Silicon): OpenJellyfish_x.y.z_aarch64.dmg
   • macOS (Intel): OpenJellyfish_x.y.z_x64.dmg
2. Install and open OpenJellyfish.
3. First launch automatically:
   • Detects bundled Python 3.12 + Node.js 20 runtime
   • Extracts backend / frontend resources to install directory
4. For DeepAgents, configure an LLM API Key in Console and test it. For a Codex / Cursor plan, install the CLI and enable Runtime as described in 4.12, then start the app and authorize the account at /superadmin. No additional LLM API key is required.
5. Click the central circular START button to launch backend services.
6. When ready, browser opens automatically at http://localhost:3000.

Desktop App 4 Tabs

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

1.3 Command Line (Developers)

Prerequisites

• Python 3.11+
• Node.js 20+
• DeepAgents: a working LLM API key. Plan path: the CLI installed and Runtime enabled, logged in, and authorized as described in 4.12
• A valid registration code (run python generate_keys.py on first deploy to generate)

Recommended: Cross-platform Launcher

# 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)

# 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)

# 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. Prepare data directory permissions (required on first deploy)
#    The app container runs as jellyfish (uid=1000); the mounted ./data must be writable by it
mkdir -p ./data/users
sudo chown -R 1000:1000 ./data

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

# 5. View logs
docker compose logs -f
docker compose logs -f openjellyfish   # App logs only
docker compose logs -f nginx          # Nginx logs only

⚠️ Step 3 is mandatory: if ./data doesn't exist, the docker daemon will create it as root, and the in-container uid=1000 process won't be able to write. FastAPI startup will then crash with sqlite3.OperationalError: unable to open database file and the container will restart in a loop. See FAQ.

Architecture

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

Data Persistence

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.