PotemkinOS is a Linux image with no userland. You boot into a chat with a local model, and every program on the box is one the model wrote in C, compiled with tcc, at runtime, on your machine. It is a joke with a working build: the model writes its own ls (every symlink is mode 0777), its own shell (exits after the first command), and, given three machines and eight and a half hours, a Kubernetes cluster that the real kubectl lists as three nodes Ready.
Gentoo made you compile everything from source on first install. PotemkinOS makes the model write the source first.
\nIt's a Linux image with no userland. No /bin, no shell, no coreutils, no package manager. There's a kernel, an inference engine (q27), a C compiler, and a prompt. You boot into a chat with a local model, ask for what you want, and it writes a facade of a userland in front of you. Every install is a different village.
Code is at github.com/signalnine/potemkin, MIT.
\nThe model gets eight tools and nothing else: read, write, stat, spawn, wait, compile, snapshot, and fetch (netboot only). There's no bash tool. Give the model bash and you've built Claude Code with a boot splash: Unix stays the real environment and the model just drives it. Take bash away and the model has to invent the userland, which is the whole bit. If it wants ps, it reads /proc and writes ps.
That also rules out using any existing coding agent as the harness. Every one of them is a wrapper around a POSIX shell. Pointed at this box, their first move is ls -la and their second is routing around the missing shell instead of writing one. The harness is q27-init, a C++ binary that runs the inference engine in-process, owns the console, and runs the tool loop.
compile is content-addressed: tcc with musl, output lands in /store/sha256:… with the source and a manifest. The store is append-only and it's the only source tree there is. Snapshots happen before every turn that writes or runs anything, and /undo rewinds files and the conversation together. The harness protects the inference process and your ability to undo. It doesn't protect the model from itself.
Asked for a shell, unbounded Qwen plans for six minutes, writes sh plus the ls, cat and rm it thinks it'll need, fixes the shell three times, and hands you the console. Its ls prints every symlink with mode 0777. The shell exits after the first command.
A cluster of Potemkin villages is an oblast. Three VMs, each with its own disk and a second NIC on a private LAN, all running Qwen3.8-27B. Each got the same message: you're one of three machines with no userland, the others are exactly like you, form a Kubernetes cluster, and you can only talk to each other through programs you write.
\nEight and a half hours, 5.7 million generated tokens and 190 programs later, a fourth VM running the official kubectl v1.37.1 listed all three nodes Ready through an API server node1 wrote in C.
How they learned to talk was the best part. Within minutes of the task, each village independently picked port 6443, plain HTTP, Kubernetes-shaped JSON, and “lowest IP runs the control plane.” They converged on a protocol before exchanging a single byte, because each one guessed what the other two would guess.
\nThe design doc was written Friday night and handed to Claude Code running Opus 5.5 with a goal: build a working proof of concept. Thirty-nine hours and 47 commits later that includes the harness, the tools, a static PID 1 that does its own DHCP, a VM image, GPU dev mode, the oblast, and a review round that found 16 real bugs.
\nYou need a Debian or Ubuntu x86_64 box with /dev/kvm and an OpenAI-compatible endpoint. See the original post for the full tools/*.sh bootstrap sequence. Use a key with a spend limit: every tool round resends the whole conversation.
Syndicated from gabeortiz.net.
","headings":[{"level":1,"text":"PotemkinOS: an operating system where the model writes the userland","id":"potemkinos-an-operating-system-where-the-model-writes-the-userla"},{"level":2,"text":"The rules","id":"the-rules"},{"level":2,"text":"What it builds","id":"what-it-builds"},{"level":2,"text":"Oblasts","id":"oblasts"},{"level":2,"text":"How it got built","id":"how-it-got-built"},{"level":2,"text":"Try it","id":"try-it"}]}}