Inside Webernetes: Rebuilding the Kubernetes Control Plane in a 140KiB Browser Payload
Developer Sam Rose has engineered "webernetes," a partial client-side port of Kubernetes to TypeScript that executes pod lifecycles, scheduling, and networking directly in the browser. By avoiding heavy WebAssembly compilation and writing custom simulations for the container runtime and CNI layers, the project achieves a gzipped footprint of just 140KiB.
Architecture of a Client-Side Control Plane
Webernetes runs a functional, simulated Kubernetes control plane directly inside the browser sandbox. To achieve a 140KiB gzipped bundle size, the project bypasses the standard path of compiling the Go source. Instead, it implements a native TypeScript partial port of core Kubernetes components.
- A partial kubelet implementation capable of managing pod lifecycles and executing liveness/readiness probes.
- A suite of ported controllers, including the pod scheduler, namespace controller, deployment/ReplicaSet trackers, and kube-proxy.
- A browser-optimized Container Network Interface (CNI) that provides virtual IP allocation, cluster DNS, and simulated packet routing.
- A container runtime executing via the standard Container Runtime Interface (CRI) boundary.
To eliminate the overhead of pulling external layers, webernetes utilizes an in-memory image registry. Rather than downloading OCI images from a registry like Docker Hub, developers define containerized processes programmatically using a TypeScript API. Images extend a BaseImage class and implement an asynchronous exec method, interacting with simulated system resources via a ProcessContext.
The Sandbox Constraint and the Rejection of WebAssembly
Compiling the upstream Go codebase of Kubernetes to WebAssembly (Wasm) was rejected due to size and environmental constraints. A minimal "hello, world" binary compiled from Go to WebAssembly yields a 540KiB gzipped payload. Compiling the complete, multi-component Kubernetes codebase would result in a massive multi-megabyte asset, violating the lightweight requirements of browser-based runtimes.
Beyond payload constraints, compiling upstream Go to WebAssembly fails due to deep dependencies on system-level OS APIs. Kubernetes relies extensively on Linux-specific kernel interfaces (such as cgroups, namespaces, iptables, and standard socket APIs) that do not compile to the browser's restricted WebAssembly sandbox. Webernetes solves this compatibility issue by mocking the underlying OS abstractions and building a simulated networking and runtime layer in TypeScript.
LLM-Assisted Porting and Verification Challenges
The project consists of nearly 100,000 lines of code across 629 files. While LLMs generated most of the codebase, achieving precise behavioral parity with the Go codebase required exhaustive manual verification. High-level LLM translations introduced subtle architectural regressions that threatened control-plane stability.
- Cache Degradation: LLMs regularly attempted to replace specialized upstream caching structures—such as LRU, expiring, FIFO, and transforming caches—with standard JavaScript Map objects, breaking core state-reconciliation mechanisms.
- Code Divergence: Code generators inserted unauthorized helper functions that departed from the upstream Go structure, complicating the side-by-side code review process.
- Test Omissions: When translating Go table-driven tests, LLMs frequently omitted test cases arbitrarily, necessitating careful reclamation of test coverage to guarantee correctness.
To mitigate these flaws, the author instituted a strict line-by-line code review process paired with hundreds of behavior-asserting tests. This ensures the client-side control plane acts as a functional model of upstream Kubernetes behavior.