Water Pistol

Category: THON

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

    ModeStorageLifecycle
    PVC VolumeDocker named volumePersists across instance recreations
    Bind MountHost directoryPersists on host filesystem
    EphemeralInside containerLost 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:

    PageFeatures
    InstancesList, filter, create, pause/resume/kill, bulk actions, recreate with PVC volume
    GroupsCRUD groups and users, transfer users between groups, start instances per group
    Lemonade ServerStatus, health, performance stats, slot management, model loading
    AI GatewayConfigure consumers, manage rate limits, setup and cleanup
    SettingsExternal 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.