clide/docs/web-deployment.md

Web Deployment

Clide runs in a browser via a two-layer stack:

Browser (code.schweitz.net)
 └─ clide-web (FastAPI + uvicorn, port 8888)
     └─ tmux (session persistence)
         └─ clide (Textual TUI)
             └─ claude code (embedded PTY)

Components

Layer	Purpose	Config
clide-web	FastAPI server: HTML page, WebSocket ↔ PTY bridge, REST API	systemd service on port 8888
tmux	Session persistence (detach/reattach on browser disconnect)	Managed by clide-web
clide	TUI IDE wrapper around Claude Code	Spawned by tmux

Installation

From the clide project root:

sudo bash deploy/install-clide-web.sh

This:

1. Installs clide-web Python package into the clide venv
2. Installs clide-web.service systemd unit
3. Enables and starts the service

First-Run Setup

After installing, run the setup wizard to configure projects directory and clide binary path:

clide-web-setup

Settings are stored in ~/.clide/clide.db as UserPreference records.

Prerequisites

• Python 3.12+ with clide venv set up (make setup)
• tmux installed (sudo dnf install tmux / sudo apt install tmux)

Reverse Proxy

For external access, configure your reverse proxy (e.g., Nginx Proxy Manager) to:

• Proxy code.schweitz.net → localhost:8888
• Enable WebSocket support

Architecture

clide-web

FastAPI application serving:

• GET / — HTML page with xterm.js terminal + toolbar
• GET /projects/{name} — Project terminal page
• WS /projects/{name}/ws — WebSocket terminal bridge
• GET /api/projects — List available git repos
• GET /api/sessions — List active tmux sessions
• GET /health — Health check for reverse proxy

WebSocket Protocol:

Prefix	Direction	Purpose
0	both	Terminal data
1	both	Control message (JSON)
2	client→server	Resize: cols,rows

tmux

Managed programmatically by clide-web. One session per project (clide-<project>).

• Browser disconnect → tmux session persists, reconnect shows current state
• Clide exit (Alt+Q) → pane-died hook auto-respawns a fresh Clide instance
• Status bar hidden for clide-web sessions only (user's other tmux sessions unaffected)
• Full environment inherited (HOME, PATH, etc.)

Keybindings

All keys pass through directly to Clide — no intermediate layer captures keys. No keybinding conflicts (unlike the previous Zellij-based setup).

Database

SQLite database at ~/.clide/clide.db shared between clide and clide-web. Uses SQLModel (Pydantic-native ORM by FastAPI's creator).

Tables:

• Project — name, path, theme, last_accessed
• Session — tmux session name, status, last_activity
• UserPreference — key/value settings (projects_dir, clide_bin, port, etc.)
• ConnectionLog — client IP, connect/disconnect timestamps

Configuration

Settings priority: environment variables > database preferences > defaults.

Environment variables (prefix CLIDE_WEB_):

Variable	Default	Description
CLIDE_WEB_HOST	0.0.0.0	Server bind address
CLIDE_WEB_PORT	8888	Server port
CLIDE_WEB_PROJECTS_DIR	/mnt/media/Projects	Directory containing git repos
CLIDE_WEB_CLIDE_BIN	clide	Path to clide binary
CLIDE_WEB_DB_PATH	~/.clide/clide.db	SQLite database path

URL Patterns

• code.schweitz.net — auto-selects first project
• code.schweitz.net/projects/clide — opens/attaches to the clide project

The toolbar dropdown allows switching projects. URL updates via history.pushState.

Operations

Service Management

# Using make targets (from clide-web/ directory)
make start-server       # Start the systemd service
make stop-server        # Stop the systemd service
make restart-server     # Restart the systemd service
make status-server      # Show service status
make logs-server        # Tail service logs

# Or directly with systemctl
systemctl status clide-web
sudo systemctl restart clide-web
journalctl -u clide-web -f

Session Management

# List sessions
tmux list-sessions

# Kill a specific session
tmux kill-session -t clide-myproject

# Kill all clide sessions
tmux list-sessions | grep ^clide- | cut -d: -f1 | xargs -I{} tmux kill-session -t {}

Files

clide-web/                      # Python package
├── clide_web/
│   ├── server.py               # FastAPI app, routes, WebSocket handler
│   ├── sessions.py             # tmux session manager
│   ├── pty_bridge.py           # PTY ↔ WebSocket bridge
│   ├── config.py               # Pydantic settings with DB overlay
│   ├── setup_wizard.py         # Interactive first-run configuration
│   └── static/
│       ├── index.html          # HTML page (toolbar + xterm.js)
│       └── vendor/             # Vendored xterm.js (no CDN dependencies)
├── pyproject.toml
└── Makefile
deploy/
├── install-clide-web.sh        # Installation script (run with sudo)
└── clide-web.service           # systemd unit file
clide/
├── models/db.py                # SQLModel table definitions (shared)
└── services/database.py        # SQLite engine and session factory