tono/docs/building.md

Building

Prerequisites

Python ≥ 3.10 Node.js ≥ 18, npm ≥ 9

First-time setup

# Install Python dependencies
pip install -e .

# Install frontend dependencies
npm install

# For running tests
pip install -e ".[dev]"

# For building desktop executables
pip install -e ".[desktop]"

Using a virtual environment is recommended:

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev,desktop]"

---

Development

Two servers run in development: the Vite frontend dev server and the Python backend. Vite proxies all API and WebSocket requests to the backend, so you only open the Vite URL in your browser.

# Terminal 1 — Python backend (http://127.0.0.1:8188)
npm run backend

# Terminal 2 — Vite frontend with hot-reload
npm run dev

Open the URL printed by Vite (typically http://localhost:5173).

Changes to Python files take effect after restarting the backend. Changes to frontend files hot-reload automatically.

---

Web deployment

Build the frontend bundle and serve the backend:

# Build frontend to frontend/dist/
npm run build

# Start the server (serves the built frontend at /)
python -m backend.main

The server listens on http://127.0.0.1:8188 by default. It serves the built frontend from frontend/dist/ and exposes the REST + WebSocket API.

The web mode is a multi-session server: each browser tab gets its own session and isolated file workspace. Local filesystem access is disabled (users upload files through the browser).

---

Desktop app

The desktop app uses pywebview to embed the frontend in a native window. The Python server runs in a background thread; the app picks a free port automatically.

# Build frontend + launch desktop app
npm run desktop

This is equivalent to npm run build && python desktop.py.

In desktop mode allow_local_filesystem=True, which means:

• Users can open files directly from their filesystem
• The plugin system is enabled (see plugins.md)

---

Building desktop executables

The build scripts use PyInstaller to produce a self-contained executable. They build the frontend first, then package everything (Python runtime, backend, frontend/dist/, demo/) into a single distributable.

macOS

Produces a .app bundle and a .dmg installer.

npm run build:mac
# Output: desktop-dist/tono.dmg

Options:

bash scripts/build-mac.sh --onefile   # Single executable instead of bundle
bash scripts/build-mac.sh --no-dmg    # Skip DMG creation

Linux

Produces a .tar.gz archive containing the app directory.

npm run build:linux
# Output: desktop-dist/tono-linux.tar.gz

Options:

bash scripts/build-linux.sh --onefile  # Single executable
bash scripts/build-linux.sh --no-tar   # Skip archive creation

Windows

Produces a tono.exe inside an output folder.

npm run build:windows
# Output: desktop-dist\tono\tono.exe

Options:

powershell -ExecutionPolicy Bypass -File scripts\build-windows.ps1 -OneFile

Note: Run the build scripts from the repo root. They expect a .venv at the repo root; if not found, they fall back to the system python / python3.

---

Runtime data directories

Mode	Directory
Development	Repo root (input/, output/, plugins/)
macOS packaged	~/Library/Application Support/tono/
Linux packaged	~/.local/share/tono/
Windows packaged	%LOCALAPPDATA%\tono\

Override with the TONO_APPDATA environment variable:

TONO_APPDATA=/my/data/dir python desktop.py

---

Key npm scripts summary

Command	Description
npm run dev	Start Vite dev server + Python backend
npm run backend	Start Python backend only
npm run build	Build frontend to frontend/dist/
npm run preview	Preview the production frontend build
npm run desktop	Build frontend + launch desktop app
npm run build:mac	Build macOS .dmg
npm run build:linux	Build Linux .tar.gz
npm run build:windows	Build Windows .exe