Code Sphere

The problem and constraints

A classroom of up to 60 students needed the same thing every one of them would eventually want at a real job: an actual VS Code, running real Python, with a real terminal, rather than a stripped-down teaching sandbox that would need to be unlearned later. The hardware available to run all of that was a single server sized for roughly half that many people at once, because in practice a school runs two classes of about 30 at a time, well short of sixty students hammering the same box at once.

That single fact (thirty real, thirty theoretical) became the constraint that shaped almost everything else. A code-server container isn’t free even when nobody’s typing: background extension processes, file watchers, and language servers cost 400 to 700 MB of memory just existing. Multiply that by sixty and a 16 GB server is over budget by three or four times before a single student writes a line of code. The platform couldn’t assume all sixty were active; it had to actively arrange for most of them not to be, most of the time, without a teacher having to manage that by hand for every class.

The second constraint was the network the students actually sit behind. School Wi-Fi and school-issued Chromebooks are notorious for blocking anything that isn’t standard web traffic, non-standard ports especially. Whatever came out of a student’s browser had to look like ordinary HTTPS traffic to port 443, indistinguishable from any other website, with no port number to remember or type.

The third constraint was who operates this thing day to day: a single teacher, with no IT department behind them. The entire setup (generating configuration, building images, starting the stack) had to collapse into a small number of scripts a non-specialist could run once, plus a “pre-warm a class” button for the one operational quirk (a 30-to-45-second cold start) that on-demand containers introduce. There’s no on-call rotation behind this platform; whatever breaks, breaks in front of a classroom, in real time.

The fourth constraint arrived after the platform already existed and was already working for plain text-based coding: the ask to also teach Pygame Zero, actual visual, interactive games. That’s a different resource shape entirely: a running game needs a screen to render to and, eventually, sound to play, inside the exact same per-student memory and CPU ceiling that was already tight before anything was drawing a frame or mixing an audio buffer. Every byte spent making a game visible or audible was a byte no longer available to the thing the platform exists to teach in the first place.

The last constraint was one specific, unglamorous reality of where this actually runs: some of the environments running or developing against this platform are Windows machines using WSL2, which has real, documented quirks around how it shares files and directories with Linux containers, quirks that don’t show up in a clean Linux CI environment but absolutely show up in front of an actual class.

Architecture

A student’s browser talks to exactly one thing on the network: Traefik, listening on a single port. Every route Traefik knows about (the login portal, and one slot per student, /code/aluno01/ through /code/aluno60/) is written into a single configuration file before any container ever starts, generated once at setup rather than discovered at runtime. That static approach exists because the more “modern” alternative, letting each container announce its own route to Traefik as it starts, quietly stopped working: Traefik’s Docker integration speaks to the Docker API at a version too old for current Docker Engine to accept, and no environment variable overrides that negotiation. Pre-declaring every route sidesteps the incompatibility completely and means Traefik never needs access to the Docker socket at all.

Behind that proxy sits a small Flask portal that is the only thing with the authority to start or stop a student’s container. When a student logs in, the portal checks their password against an Argon2id hash, starts their specific container if it isn’t already running, and waits (polling the container’s own HTTP port rather than just sleeping a fixed number of seconds) until code-server inside it is actually ready to answer. A background thread in the same portal walks the list of running containers on a timer and stops whichever ones have gone quiet, returning their memory to whatever student logs in next. Every container the portal creates starts completely fresh instead of resuming a stopped one: restarting from scratch each time is what guarantees a fresh access token can never collide with a token from a previous session.

Once a student’s environment is running, it offers more than a terminal. A monitor view, built on noVNC, shows whatever the student’s Pygame Zero game is actually rendering: necessary the moment “coding” means “coding something you can see move on screen.” Audio came later and had to fight for the same tiny resource budget the video path was already spending: PulseAudio inside the container publishes a virtual sink, a second websockify process (the same tool already bridging the video, so no new dependency) carries that raw audio to the browser over its own WebSocket, and a small script decodes it with the Web Audio API. The two channels, video and audio, run side by side through the same proxy, on the same per-student cgroup limit, sharing a budget that was already accounted for before either of them needed to make a sound.