Run multiple VS Code sandbox instances with nginx SSL, groups-based user management, and optional local LLM inference

THON

Run multiple VS Code sandbox instances concurrently with nginx SSL reverse proxy, groups-based user management, persistent workspaces, and optional local LLM inference via Lemonade Server.

Features

Unified CLI: thon init, thon setup, thon run — one config file (thon.yaml) for everything
Multi-Instance: Multiple concurrent VS Code sandboxes from a single command
Groups-Based: Define users and groups in YAML or manage via dashboard
Web Dashboard: Streamlit dashboard for instance, group, Lemonade, and gateway management
SSL/TLS: Automatic nginx reverse proxy with mkcert or openssl certificates
Persistent Workspaces: PVC Docker volumes or host bind mounts for workspace persistence
Local LLM: Optional Lemonade Server integration for local inference
Semantic Indexing: Embedding model for Kilo Code's semantic code search
AI Gateway: Optional APISIX gateway with per-user or per-group rate limiting and API keys
Authentication: Local password for dashboard; OIDC/OAuth2 (GitHub, GitLab, LinkedIn) for REST API
Config Files: Store and manage groups YAML, kilo.json, and VS Code settings in the database
Kilo Code Ready: Auto-generated config with experimental flags and indexing for Kilo Code

Quick Start

1. Prerequisites

# One-time host setup
bash ./scripts/setup.sh

Installs: python3, nginx, docker.io, mkcert, openssl

2. Build Docker Image

docker build -t waterpistol/thon:latest ./

3. Initialize Configuration

# Interactive setup wizard (recommended)
python -m thon init

# Or non-interactive (CI-friendly)
python -m thon init --non-interactive

This creates a thon.yaml config file with all settings.

4. Setup and Run

# Install prerequisites and configure all components
python -m thon setup

# Start VS Code instances
python -m thon run

Alternatively, use main.py directly:

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

Each user gets their own VS Code sandbox at https://<ip>/<endpoint_path>/.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                         Host Machine                         │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                    nginx (443)                       │    │
│  │         SSL termination + WebSocket proxy           │    │
│  └──────────────────────┬──────────────────────────────┘    │
│                         │                                    │
│  ┌──────────────────────┼──────────────────────────────┐    │
│  │                Docker Network                        │    │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │    │
│  │  │  Sandbox 1  │  │  Sandbox 2  │  │  Sandbox 3  │ │    │
│  │  │ code-server │  │ code-server │  │ code-server │ │    │
│  │  │   :8443     │  │   :8444     │  │   :8445     │ │    │
│  │  └─────────────┘  └─────────────┘  └─────────────┘ │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │           Lemonade Server (Optional)                 │    │
│  │    Chat model + Embedding model (semantic search)    │    │
│  │                   :13305                             │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │         APISIX AI Gateway (Optional)                 │    │
│  │    Rate limiting + per-user/group API keys           │    │
│  │    Chat route + Embedding route                      │    │
│  │                   :9080                              │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

Components

Component	Role
thon CLI	Unified entry point: `thon init`, `thon setup`, `thon run`, `thon config`
main.py	Orchestrates sandbox creation, nginx configs, workspace setup
Streamlit Dashboard	Web UI for instance, group, Lemonade, and gateway management (:8501)
FastAPI REST API	Programmatic API for instances, groups, Lemonade, gateway, auth (:8100)
nginx	SSL termination + WebSocket proxy (per-port server blocks)
code-server	VS Code in the browser, runs HTTP inside each sandbox
Lemonade Server	Optional local LLM inference (chat + embedding models)
APISIX Gateway	Optional rate limiting with per-user or per-group API keys

Network Modes

Network mode is auto-detected from the server-returned endpoint format:

Mode	Endpoint Format	Detection
Host	`127.0.0.1:8443`	No `/` after port
Bridge	`127.0.0.1:52322/proxy/8443`	`/proxy/` in endpoint

Workspace Persistence

Mode	Storage	Lifecycle
PVC Volume	Docker named volume (`thon-workspace-*`)	Persists across instance recreations
Bind Mount	Host directory (`--workspace-dir`)	Persists on host filesystem
Ephemeral	Inside container	Lost when container is removed

PVC volumes are created automatically when users are imported via the dashboard or thon.yaml. When a sandbox is recreated, the same PVC volume is reattached.

Next Steps

Installation Guide - Detailed setup instructions
Dashboard - Streamlit web dashboard for instance management
Lemonade Server - Local LLM inference setup
AI Gateway - APISIX rate limiting and API key management
Configuration - Full configuration reference
CLI Reference - Command-line options

THON - The Hackathon Organizer Node