From a Single VSCode Example to THON — The Hackathon Organizer Node

---

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:
      - dave

SSL 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 down

One 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 run

Each 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.