I ported Kubernetes to the browser

Last week I released webernetes, a partial port of Kubernetes to TypeScript to make it possible to run clusters in the browser. I ended up generating almost 100,000 lines of code in 552 commits across 629 files. It took me 2 months.

The demo below is a webernetes cluster. It runs entirely in your browser, and it’s genuinely doing much of the same work a real Kubernetes cluster does: pod lifecycles, cluster DNS and networking, container garbage collection, IP allocation, Deployment and ReplicaSet tracking, and more. The blue dots represent pods sending requests to each other.

Bookmark this sectionWait, what am I looking at?

The question I’ve been getting most often is: “Did you compile Kubernetes to WebAssembly?” The answer is no. A simple “hello, world!” Go program compiled to WebAssembly is ~540KiB gzipped. That alone is already bigger than webernetes, which is ~140KiB gzipped. Compiling all of Kubernetes to WebAssembly would no doubt mean sending megabytes over the wire. I did try to check, but unfortunately there are compile-time errors because Kubernetes calls system-level APIs that aren’t available in the browser.

Instead, webernetes is:

• A partial port of Kubernetes’ “kubelet” binary, enough to run pods and probe them.
• Ports of several Kubernetes “controllers”: pod scheduler, namespace controller, kube-proxy, deployment controller, and a few more.
• A browser-based take on a container network interface (CNI), so pods can talk to each other over a simulated network.
• A browser-based container runtime, which the kubelet talks to over the container runtime interface (CRI) to run containers.
• An API for interacting with your webernetes cluster to do things like apply manifests and watch resources.

As a result of the desire to keep webernetes small, it doesn’t pull real images from a registry like Docker Hub. Instead, it has its own browser-based registry and you define images using a TypeScript API. Images look like this:

1import * as w8s from "@ngrok/webernetes";2 3class HelloWorld extends w8s.BaseImage {⋯4	static readonly imageName = "hello-world";5	static readonly imageVersion = "1.0";6 7	async exec(ctx: w8s.ProcessContext, argv: string[]): Promise<number> {⋯8		ctx.listenHttp(8080, async (_ctx, request) => {⋯9			return {⋯10				status: 200,11				body: "Hello, world!",12			};13		});14		return await ctx.waitUntilKilled();15	}16}

To deploy your image into a cluster, you do this:

1import * as w8s from "@ngrok/webernetes";2 3class HelloWorld extends w8s.BaseImage {⋯4	// as before ...5}6 7const cluster = new w8s.Cluster();8await cluster.registerImage(HelloWorld);9 10const [pod] = await cluster.apply([⋯11	{⋯12		apiVersion: "apps/v1",13		kind: "Deployment",14		metadata: { name: "hello-world-deployment" },15		spec: {⋯16			replicas: 1,17			selector: {⋯18				matchLabels: { app: "hello-world-pod" },19			},20			template: {⋯21				metadata: {⋯22					labels: { app: "hello-world-pod" },23				},24				spec: {⋯25					containers: [⋯26						{⋯27							name: "hello-world-container",28							image: "hello-world:1.0",29						},30					],31				},32			},33		},34	},35]);

And then you can use the webernetes API to interact with the cluster, like this:

1// List all pods in the default namespace2const pods = await cluster.api.corev1.listNamespacedPod({⋯3	namespace: "default",4});5 6// Watch for changes to pods in all namespaces7const informer = cluster.informer("pods", (type, pod) => {⋯8	console.log(`pod ${type}: ${pod.metadata?.name}`);9});10 11// Stop the informer when you're done12await informer.stop();13 14// Listen to pods sending requests and responses to each other.15// This is how I visualise the moving dots above.16cluster.on("request", (event) => {⋯17	console.log(`request: ${event.request.method} ${event.request.url}`);18});19cluster.on("response", (event) => {⋯20	console.log(`response: ${event.response?.status}`);21});22 23// Use the cluster network to send a request to a pod. This will also trigger24// the request/response event handlers above.25const pod = pods.items[0];26const resp = await cluster.fetch(`http://${pod.status?.podIP}:8080/`);27console.log(resp.body); // "Hello, world!"

There are plenty more examples in the webernetes repository.

Webernetes is intended to be used to make interactive Kubernetes content; it’s not a production-ready Kubernetes distribution. It doesn’t need to run real images. It just needs a way for creators to set up specific workloads to illustrate the thing they’re trying to teach.

Over time, it is my intention to expand webernetes to support more Kubernetes features. Right now, it doesn’t support ConfigMaps, Secrets, pod resources, persistent volumes, and a whole host of other things I haven’t needed yet. As I make more content with this library, I’ll implement more of what I need.

If you’re looking to build on webernetes and it doesn’t support something you need, please reach out! I’m s.rose@ngrok.com and I’d be happy to help you become a contributor.

Bookmark this sectionIs this just slop?

Almost all of the webernetes code was authored by LLMs. I expect people to be dubious of the project as a result. I expect to be accused of slop-porting Kubernetes for views, but I’m going to try to show you that’s not what I’ve done.

I did two things that I think make this a slop-free project:

1. I reviewed every line of code.
2. I created hundreds of tests that assert webernetes behaves the same as a real cluster.

The first point, by far the most time-consuming, is how I gained the confidence that the vast majority of the code is line-for-line identical to the Kubernetes Go codebase. The second point is how I made sure the lexical similarity translates to identical behaviour in practice.

Any mistakes that remain in the codebase after my review are on me, and I’ve no doubt some exist. If you find any, please let me know by opening an issue.

Bookmark this sectionWhy review the code?

The stories I’ve read about LLMs being used to write a C compiler or port Bun from Zig to Rust were made possible by having an automated way to assert correctness. Anthropic had plenty of existing C compilers to compare against, and Bun had a large existing test suite that its maintainers trusted enough to merge over 1 million lines of new Rust code without manual review.

I didn’t have those things. If I wanted a test suite, I’d need to write it myself. If I wanted to compare against real Kubernetes, I’d need to figure out a way to do it.

Most of the code in webernetes is ported from the Kubernetes Go codebase. I ported it with LLMs because I was confident that would be faster than typing it by hand, but the problem I quickly encountered was that LLMs suck at porting code. No matter how hard I tried, they kept making mistakes. The mistakes came in a few flavours:

1. Shortcuts. This seemed to happen more when porting larger files, and it made me wonder if I was battling with post-training choices designed to make LLMs less verbose. An example of a shortcut I saw a lot: Kubernetes contains a lot of different types of cache. There’s an LRU cache, an expiring cache, a FIFO cache, a transforming cache, and more. Instead of implementing these, I’d catch the LLM using a Map instead, leading to incorrect behaviour.
2. Trying to be too helpful. The LLM would try to tidy up code by inventing helper functions that didn’t exist in the original Go code. Often, these helpers were harmless, but sometimes they’d have subtle differences. Either way, they made the code harder for me to review side-by-side with the original, so I asked the LLM to remove them.
3. Stuff just… missing. This happened most often when porting over table tests from Go. If you’re unfamiliar, table tests look like this. They are arrays of test cases with some test code underneath. The LLM would arbitrarily omit tests and I’d have to ask it why. Sometimes it would talk about the test not being applicable. Occasionally that was true, but usually the LLM would own up to omitting the test by mistake.

I know at least a few of you are screaming “SKILL ISSUE” and are ready to comment saying I need to get better at prompting. That could be true! I would love to see an example prompt that perfectly one-shots porting this table test from Go to TypeScript. You stand to save me an enormous amount of time in future.

Until then, for me to have confidence in an LLM porting something, I need to review the output. I’m not aware of any shortcuts.

Bookmark this sectionWhat the tests look like

It’s all well and good to know that the code is side-by-side identical, but does it actually work? Go and JavaScript have different runtime environments, so it was always possible that the same code would behave differently in each. I also ended up having to create JavaScript versions of channels, mutexes, Go’s select statement, and other Go-isms. I needed to know they worked in non-trivial scenarios.

To feel good about this, I wrote tests where the exact same code is run against both webernetes and a k3s cluster. To do this, I needed to have an API for webernetes that matched an existing Kubernetes API. I picked kubernetes-client/javascript because it’s the official client library for Kubernetes in JavaScript, and it has TypeScript types.

Here’s an example test:

1import { expect, it } from "vitest";2import { kubernetes } from "../../test/harnesses/kubernetes";3 4// `kubernetes.describe` does some magic behind the scenes to set up either a5// k3s (https://k3s.io/) cluster or a webernetes cluster and pass that in via6// the `context` argument.7//8// Then I can run either `pnpm test:node` or `pnpm test:browser` to run tests9// against k3s using a Node environment, or webernetes using a headless browser.10kubernetes.describe("Pods", (context) => {⋯11	const { core } = context;12	const { getTestNamespace, waitFor } = context.helpers;13 14	it("should be able to delete a pod", async () => {⋯15		// Tests get their own unique namespace for isolation from each other16		const namespace = await getTestNamespace();17 18		await core.createNamespacedPod({⋯19			namespace,20			body: {⋯21				metadata: { name: "delete-test" },22				spec: {⋯23					containers: [⋯24						{⋯25							name: "pause",26							// Webernetes has an implementation of this image built-in27							image: "registry.k8s.io/pause:3.10",28						},29					],30				},31			},32		});33 34		// Make sure the pod definitely exists before moving on.35		await waitFor(async () => {⋯36			const pods = await core.listNamespacedPod({ namespace });37			const found = pods.items.find((pod) => pod.metadata?.name === "delete-test");38			expect(found).toBeDefined();39		});40 41		await core.deleteNamespacedPod({⋯42			name: "delete-test",43			namespace,44		});45 46		// Wait until the pod is definitely gone before declaring success.47		await waitFor(async () => {⋯48			const pods = await core.listNamespacedPod({ namespace });49			const found = pods.items.find((pod) => pod.metadata?.name === "delete-test");50			expect(found).toBeUndefined();51		});52	});53});

The core object, with its createNamespacedPod and deleteNamespacedPod methods, is an example of the kubernetes-client/javascript API. The kubernetes.describe(..) helper I created to run these tests injects a core object that points at k3s when I run pnpm test:node, and at webernetes when I run pnpm test:browser.

These are the integration tests for the project. They make sure that my porting work is correct and my custom browser-based container runtime and cluster network are working in a way that matches a real cluster.

Whenever I spot a bug while working with the library, the first thing I do is create a test that passes against k3s and fails against webernetes. Then I use that feedback loop to get an LLM to help me understand and fix the problem.

At time of writing, webernetes has 204 integration tests. They sit alongside 1,855 unit tests, most of which are direct ports from the Kubernetes Go codebase.

Bookmark this sectionIs review and testing really enough to make it not-slop?

I think so, yes.

When I got PRs from human beings, back in the good old days, what I expected to find were good tests and good code. I have the same expectation of LLMs. The difference in 2026 is that, while I generally trusted my human colleagues to do good work, I feel quite safe assuming that an LLM won’t. You need to review its output, and you need to insist on tests.

It’s not enough to do one or the other, either. Without reviewing at least the test code, how do you know what success criteria the LLM is working to? And if you review all of the code but have no tests, do you really trust your squishy human brain to reason through every possibility? I don’t. I don’t even trust myself to do this with my own hand-written code.

Because they don’t get tired and they type really fast, I think LLMs complement our human weaknesses really well. It’s fun to ask the LLM to come up with edge cases you haven’t thought of, then write tests for them if they make sense. You can do this dozens of times if you want, until the suggestions are nonsense. The LLM won’t mind!

Combining my unique strengths of taste and understanding with the LLM’s ability to write fast, without fatigue or wrist pain, has been the biggest step change in what feels possible since I started my career in 2012.

Bookmark this sectionNumber crunching

Given the retrospective nature of this post, I thought it’d be fun to make some graphs showing how the project evolved. The first one shows lines of code over time.

This graph doesn’t quite capture the full reality. Early work was done in a branch of the repo behind this blog site, because it wasn’t obvious to me at the time that it would become its own project. The first commit to what would become the https://github.com/ngrok/webernetes repo was on April 21st.

The graph also says ~126k lines, not the ~100k that I claimed at the start of the post. This is because the 100k number excludes non-TypeScript, comments, and the demo app.

Make sure you really take in the magnitude of the two Y axes. Coding agents consume far more cached input tokens than any other type of token, especially if you’re often filling up long context windows.

Bookmark this sectionSam, what on earth happened in the last week?

Yeah… about that.

I was working on the demo app and thought it would be cool if it had support for Deployments. I didn’t think it would take long. I was wrong. In my panic, I threw lots of tokens at the problem.

The LLM’s first attempt at porting the required components missed a huge amount of functionality, so I kicked off a team of agents to identify the chain of dependencies and port each component over with even more sub-agents. I then used yet another set of sub-agents to review everything.

I’m not sure how I feel about this style of working with LLMs, but it undeniably got the job done more quickly than I would have. I still did my manual review at the end, but the token efficiency feels extremely poor.

My time was still the most expensive line item in the project, even at the end.

Bookmark this sectionConclusion

If you got this far in the post, you may also enjoy watching the series I recorded with my colleague Ryan Blunden chronicling the making of webernetes as it happened. You’ll get to see all of my early misplaced optimism, as well as some insight into how I work mostly hands-free with voice control and eye tracking.

Part 3 is coming soon!

Please take webernetes for a spin! File issues! Email me at s.rose@ngrok.com when you build something cool or get stuck! I want this project to thrive and make a difference, and I can’t do that without your help.