How a simple OpenSandbox VSCode example evolved into a full-featured hackathon platform with multi-instance management, local LLM inference, AI gateways, and a web dashboard.
The OpenSandbox repository ships a straightforward examples/vscode/main.py — a single script that spins up one VS Code sandbox instance via the OpenSandbox SDK. It’s clean, it works, and it gets you coding in a browser in seconds. But what happens when you need to run a hackathon for 30, 50, or 100 people? That’s where THON comes in.
THON — The Hackathon Organizer Node — takes the core idea behind that example and scales it into a production-ready platform for multi-developer environments. Here’s what changed, what was added, and why.
The Starting Point: One Instance, One User
The original VSCode example does one thing well: it creates a single code-server sandbox, connects to it, and gives you a URL. There’s no SSL, no user management, no persistence. It’s a proof of concept — and a great one — but it wasn’t built for the chaos of a live hackathon.
What THON Adds
Multi-Instance, Groups-Based Orchestration
Instead of one sandbox, THON runs dozens or hundreds concurrently. Users are organized into groups via a thon.yaml config file (or the web dashboard), and each user gets their own isolated VS Code sandbox with a workspace at /workspace/{group}/{username}. A single command — thon run — launches them all.
groups:
alpha:
users:
- alice
- bob
beta:
users:
- daveSSL Termination and Reverse Proxy
The original example runs HTTP directly. THON places an nginx reverse proxy in front of every instance with automatic SSL via mkcert (CA-trusted) or openssl (self-signed fallback). WebSocket support is built in for live editing. Each instance gets its own nginx server block, and the CA root certificate is served at https://{ip}/ca.crt so remote participants can trust the connection.
Persistent Workspaces
Hackathon participants can’t lose their work if a container restarts. THON supports three workspace modes:
| Mode | Storage | Lifecycle |
|---|---|---|
| PVC Volume | Docker named volume | Persists across instance recreations |
| Bind Mount | Host directory | Persists on host filesystem |
| Ephemeral | Inside container | Lost on removal |
PVC volumes are created automatically and reattached when sandboxes are recreated — participants pick up right where they left off.
Local LLM Inference with Lemonade Server
This is where THON goes beyond a simple sandbox manager. Through integration with Lemonade Server, each sandbox gets access to a local, OpenAI-compatible LLM endpoint — no API keys to external services, no data leaving the machine. It runs as a systemd service on the host and scales automatically based on user count:
- Chat model: Default is Gemma 4 31B (Q8_K_XL), configurable to any GGUF checkpoint
- Embedding model: Enables semantic code search inside Kilo Code
- Per-user scaling: Context size and parallel slots scale with the number of participants
The kilo.json configuration is auto-generated and injected into each sandbox, so Kilo Code, Continue, or Cline extensions connect out of the box.
AI Gateway with Rate Limiting
For larger events, THON includes an optional APISIX API Gateway that sits between sandbox instances and the Lemonade server. It provides:
- Per-user API keys — each participant gets their own key and rate limit
- Per-group shared keys — teams share capacity, with limits scaled by group size
- Redis-backed rate limiting — consistent enforcement across multiple gateway instances
- Token-based limits — rate limiting on actual LLM token consumption, not just requests
Two routes are created automatically: /v1/chat/completions for chat and /v1/embeddings for semantic indexing.
Web Dashboard
Managing 50 sandbox instances from the command line is impractical. THON includes a Streamlit dashboard with five pages:
| Page | Features |
|---|---|
| Instances | List, filter, create, pause/resume/kill, bulk actions, recreate with PVC volume |
| Groups | CRUD groups and users, transfer users between groups, start instances per group |
| Lemonade Server | Status, health, performance stats, slot management, model loading |
| AI Gateway | Configure consumers, manage rate limits, setup and cleanup |
| Settings | External IP, config file management (upload/edit/delete from database) |
A FastAPI REST API with Swagger UI is also available for programmatic access.
Unified CLI
The original example was a single script. THON provides a proper CLI:
thon init # Interactive setup wizard
thon setup # Install prerequisites + configure
thon run # Start instances
thon run --group alpha # Start one group
thon config validate # Check config
thon cleanup # Tear downOne thon.yaml config file replaces a dozen CLI flags.
Authentication
THON supports two independent auth mechanisms:
- Local password for the Streamlit dashboard (single shared password via
AUTH_LOCAL_PASSWORD) - OIDC/OAuth2 for the REST API (GitHub, GitLab, LinkedIn via PKCE flow)
Network Auto-Detection
The original example didn’t need to think about network modes. THON auto-detects host vs. bridge networking from the server-returned endpoint format — no CLI flags required. It handles the nginx proxy_pass configuration correctly for both modes, avoiding common pitfalls like path doubling and Service Worker scope errors.
The Full Picture
┌─────────────────────────────────────────────────────────────┐
│ Host Machine │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ nginx (443) │ │
│ │ SSL termination + WebSocket proxy │ │
│ └──────────────────────┬──────────────────────────────┘ │
│ │ │
│ ┌──────────────────────┼──────────────────────────────┐ │
│ │ Docker Network │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Sandbox 1 │ │ Sandbox 2 │ │ Sandbox 3 │ │ │
│ │ │ code-server │ │ code-server │ │ code-server │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────┐ ┌──────────────────────────────┐ │
│ │ Lemonade Server │ │ APISIX AI Gateway (Opt.) │ │
│ │ Chat + Embedding │ │ Rate limiting + API keys │ │
│ │ :13305 │ │ :9080 │ │
│ └──────────────────────┘ └──────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘Getting Started
# One-time setup
bash ./setup.sh
# Build the sandbox image
docker build -t waterpistol/thon:latest ./
# Interactive configuration
thon init
# Install and configure
thon setup
# Launch
thon runEach participant gets their own VS Code environment at https://<ip>/<endpoint_path>/ with optional LLM-powered coding assistance.
What’s Next
THON is actively developed. On the roadmap:
- Luma invites — invite codes for onboarding new users
- WebSocket real-time updates — live instance state changes pushed to the dashboard
- Instance templates — pre-configured sandbox setups with image, extensions, and env vars
- Usage analytics — per-user resource usage and token consumption
- Multi-server support — manage sandboxes across multiple host machines
- Kubernetes native — deploy THON as a Kubernetes resource
Join the Community
THON is open source under Apache 2.0. Visit the docs or join the community server for help, updates, and discussion. The source code is available on GitHub.
Not so sure about the name yet.
