Installation and Setup

Prerequisites

System Requirements

OS: Linux (Ubuntu 24.04+ recommended)
Docker: 20.10+ with Docker daemon running
Python: 3.10+
Memory: 4GB+ RAM (8GB+ recommended for multiple instances)
GPU: AMD ROCm or NVIDIA CUDA (optional, for Lemonade inference)

Network Requirements

Ports 443 (nginx HTTPS) and 80 (nginx HTTP) available
Port 8100 for FastAPI REST API
Port 8501 for Streamlit dashboard
Port 13305 available for Lemonade Server (optional)
Port 9080 available for APISIX AI Gateway (optional)
Unique port per VS Code instance (starting from 8443 by default)

Alternative: Using main.py Directly

If you prefer the traditional CLI approach without thon.yaml:

Create Groups Configuration

Create groups.yaml in your project directory:

groups:
  alpha:
    users:
      - alice
      - bob
  beta:
    users:
      - charlie
      - dave
  gamma:
    users:
      - eve

Run from YAML

python ./scripts/main.py --groups groups.yaml --external-ip YOUR_EXTERNAL_IP

Run from Database

After importing groups via the dashboard, you can start instances from the database:

# Start all groups from database
python ./scripts/main.py --from-db --external-ip YOUR_EXTERNAL_IP

# Start a specific group from database
python ./scripts/main.py --from-db --group beta --external-ip YOUR_EXTERNAL_IP

When using --from-db, PVC workspace volumes from the database are reattached automatically, preserving user data across instance recreations.

Configure SSL Certificates

Option A: mkcert (Recommended for Development)

# Install local CA
mkcert -install

# Generate certificate for your IP
mkcert -cert-file /etc/nginx/ssl/server.crt \
       -key-file /etc/nginx/ssl/server.key \
       165.245.138.159 localhost

Option B: Let's Encrypt (Production with Domain)

Set in thon.yaml:

nginx:
  domain: "your-domain.com"
  ssl_provider: "certbot"
  certbot_email: "[email protected]"

Then run python -m thon setup to generate certificates automatically.

Or manually:

sudo certbot certonly --standalone -d your-domain.com
sudo cp /etc/letsencrypt/live/your-domain.com/fullchain.pem /etc/nginx/ssl/server.crt
sudo cp /etc/letsencrypt/live/your-domain.com/privkey.pem /etc/nginx/ssl/server.key

Option C: Self-Signed (Fallback)

Set ssl_provider: "openssl" in thon.yaml. THON will generate self-signed certificates with the IP/domain in the SAN extension.

Optional: Lemonade Server Setup

For local LLM inference with Kilo Code, Continue, or Cline extensions.

Quick Setup

bash ./scripts/setup-lemonade.sh \
    --groups groups.yaml \
    --generate-keys \
    --external-ip YOUR_EXTERNAL_IP

This will:

Install Lemonade Server from PPA
Configure for your GPU backend
Generate API keys
Download the default chat model (gemma-4-31b-it)
Download the default embedding model (harrier-oss-v1-0.6b)
Create kilo.jsonc for Kilo Code (with semantic indexing config)

Without Embedding Model

bash ./scripts/setup-lemonade.sh \
    --groups groups.yaml \
    --generate-keys \
    --external-ip YOUR_EXTERNAL_IP \
    --no-embedding

Custom llama.cpp Build (AMD MI300X)

For optimal performance on AMD MI300X GPUs:

# Build llama.cpp with ROCm support
bash ./build-amd-mi300x-llama-server.sh

# Then run setup with system binary preference
bash ./scripts/setup-lemonade.sh \
    --groups groups.yaml \
    --generate-keys \
    --external-ip YOUR_EXTERNAL_IP

See Lemonade Server for detailed configuration options.

Optional: AI Gateway Setup

For rate limiting LLM API access with per-user or per-group API keys:

Quick Setup

# Install APISIX (or use INSTALL_GATEWAY=true during initial setup)
INSTALL_GATEWAY=true bash ./scripts/setup.sh

# Setup gateway with per-user rate limiting (includes embedding route)
python scripts/apisix_gateway.py setup --groups groups.yaml \
    --lemonade-url http://127.0.0.1:13305

# Per-group (shared API key per group)
python scripts/apisix_gateway.py setup --groups groups.yaml \
    --lemonade-url http://127.0.0.1:13305 --per-group

# Without embedding route
python scripts/apisix_gateway.py setup --groups groups.yaml \
    --lemonade-url http://127.0.0.1:13305 --no-embedding

Running with Gateway

# Per-user: each user gets their own API key and rate limit
python ./scripts/main.py --groups groups.yaml --external-ip 1.2.3.4 --gateway

# Per-group: all users in a group share an API key with combined rate limit
python ./scripts/main.py --groups groups.yaml --external-ip 1.2.3.4 \
    --gateway --gateway-per-group

# With Redis-backed rate limiting (recommended for multi-gateway)
python ./scripts/main.py --groups groups.yaml --external-ip 1.2.3.4 \
    --gateway --gateway-redis-host 127.0.0.1

See AI Gateway for detailed configuration options.

Running with Lemonade

After setting up Lemonade Server:

python ./scripts/main.py \
    --groups groups.yaml \
    --external-ip YOUR_EXTERNAL_IP \
    --lemonade kilo.jsonc

This injects kilo.jsonc into each sandbox at /home/vscode/.config/kilo/config.json, enabling Kilo Code to connect to your local LLM with both chat and semantic indexing.

Optional: Langfuse Observability

For LLM tracing and observability via Langfuse:

# Via CLI flags
python ./scripts/main.py --groups groups.yaml --external-ip 1.2.3.4 \
    --langfuse \
    --langfuse-public-key "pk-lf-..." \
    --langfuse-secret-key "sk-lf-..." \
    --langfuse-base-url "https://cloud.langfuse.com"

# Or via environment variables
export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_BASEURL="https://cloud.langfuse.com"
python ./scripts/main.py --groups groups.yaml --external-ip 1.2.3.4 --langfuse

# Combined with Lemonade + Langfuse
bash ./scripts/setup-lemonade.sh --groups groups.yaml --generate-keys --external-ip 1.2.3.4 --langfuse
python ./scripts/main.py --groups groups.yaml --external-ip 1.2.3.4 --lemonade kilo.jsonc --langfuse

When Langfuse is enabled:

LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASEURL are injected as env vars into each sandbox
"plugin": ["opencode-plugin-langfuse"] is added to the generated kilo.jsonc
experimental.openTelemetry is set to true in the kilo config
All LLM traces are automatically sent to your Langfuse dashboard

Or in thon.yaml:

langfuse:
  enabled: true
  public_key: "pk-lf-..."
  secret_key: "sk-lf-..."
  base_url: "https://cloud.langfuse.com"

Verification

Check Services

# Docker is running
docker ps

# Nginx is configured
ls /etc/nginx/sites-enabled/

# Lemonade server is running (if configured)
sudo systemctl status lemonade-server

# Config is valid
python -m thon config validate

Access VS Code

Open browser to the URL shown in terminal output

For mkcert certificates, install the CA:

# Download CA certificate
curl -o ca.crt https://YOUR_IP/ca.crt

# Install in browser (varies by browser)
# Chrome: Settings > Privacy > Certificates > Authorities > Import
# Firefox: Settings > Privacy > Certificates > View Certificates > Authorities > Import

Config File Management

The dashboard's Settings page and the /api/config-files REST API allow you to store configuration files in the database:

Config Key	Description
`config_groups_yaml`	Groups and users definition
`config_kilo_json`	Kilo Code provider config
`config_vscode_settings`	VS Code settings for each sandbox

When main.py runs without CLI flags (e.g., python ./scripts/main.py without --groups or --lemonade), it reads these from the database. CLI flags always take precedence over database-stored configs.

Uninstallation

Remove VS Code Instances

# Clean up nginx configs
python ./scripts/main.py --cleanup

# Or use thon CLI
python -m thon cleanup

# Stop all sandboxes (via Docker)
docker ps -q | xargs -r docker stop

Remove Lemonade Server

sudo systemctl stop lemonade-server
sudo apt-get remove --purge lemonade-server
sudo rm -rf /var/lib/lemonade
sudo rm -rf /etc/systemd/system/lemonade-server.service.d

Remove All

# Remove packages
sudo apt-get remove --purge nginx docker.io mkcert

# Remove certificates
sudo rm -rf /etc/nginx/ssl

# Remove Docker image
docker rmi waterpistol/thon:latest

# Remove database
rm -rf ~/.thon/thon.db

Installation and Setup

On this page