# Putting the "You" in CPU: an MDX explainer you can self-host > hackclub/putting-the-you-in-cpu is a long-form technical article about what happens between typing a command and a program running. The repository is the article's source: Astro, MDX chapters, and a Docker image that serves the built site through nginx. **hackclub/putting-the-you-in-cpu** — A technical explainer by @kognise of how your computer runs programs, from start to finish. - Repository: https://github.com/hackclub/putting-the-you-in-cpu - Website: https://cpu.land - Stars: 5,559 · Forks: 196 - Language: MDX - License: MIT - Published: 2026-09-22 · Updated: 2026-09-22 · Language: en - Canonical page: https://hysenlabs.com/projects/hackclub-putting-the-you-in-cpu ## The gap this explainer fills, and who it is written for The README opens with the author's own admission: a lot of low-level knowledge, but no single thread connecting it. The questions listed there are the ones the article exists to answer. Are programs really executing directly on the CPU, or is something else going on? Syscalls get used, but how do they work, and what are they really? How do multiple programs run at the same time? The stated audience is the person who is not going to college for this. The README says there are not many comprehensive systems resources outside a degree, and that the research involved sifting through sources of varying quality and sometimes conflicting information. Weeks of reading and roughly 40 pages of notes turned into the article the author wished existed. That framing matters: this is not a textbook and not a specification. It is one person's reconstruction of the path from machine startup to program execution, written to be read in order. The README also names a shortcut. If you think you already know the material, it points you at chapter 3, "How to Run a Program," and claims you will still learn something. That is the author's own confidence, not a measured result, but it tells you where the densest material sits. ## Astro, MDX and a build that ends in static files The repository is a website, not a library. The primary language is MDX, and package.json marks the package private with version 0.0.1, so there is nothing to publish or import. The dependency list is what you would expect from an Astro content site: @astrojs/mdx for the chapter format, @astrojs/sitemap, @astrojs/vercel for deployment, shiki for code highlighting, rehype-external-links and rehype-preset-minify for the HTML pipeline, postcss-nesting for CSS, and puppeteer plus jsdom for the PDF generator. The data flow is short. bun installs the lockfile, astro build reads the MDX under src/ and emits a dist/ directory, and nginx serves that directory as static files. There is no server-side runtime, no database, and no API. The Dockerfile makes the split explicit with two stages: a build stage on dhi.io/bun:1-dev that runs bun install --frozen-lockfile and then bun run build, and a runtime stage on dhi.io/nginx:1 that copies nginx.conf and the built /app/dist/ into /usr/share/nginx/html/. The runtime image is nginx, so the deployment surface is as small as the article's own architecture. One detail worth noticing: the build stage sets ENV PUPPETEER_SKIP_DOWNLOAD=true. Puppeteer is a devDependency and pdfgen.js exists at the top level, but the container build deliberately avoids downloading a browser. The PDF path is not part of the image. ## Installing it and reading a chapter locally The README gives no install instructions, because the intended way to consume this is the hosted site at cpu.land. The repository is what you clone when you want the source, a local preview, or your own copy. package.json defines three scripts, and the lockfile is bun.lock, so bun is the package manager the repository is set up for. Install the dependencies from the repository root: ```bash bun install --frozen-lockfile ``` The frozen flag matches what the Dockerfile uses, so it installs exactly the versions pinned in bun.lock. If that file is out of sync with package.json, the command fails rather than silently resolving newer versions. Start the development server: ```bash bun run dev ``` This runs astro dev, which serves the MDX chapters with hot reload. You should see Astro print a local URL in the terminal; open it and the first chapter, "The Basics," is the entry point the README links to. To produce the same static output the container serves: ```bash bun run build bun run preview ``` The build writes to dist/, and preview serves that directory locally so you can check the minified, link-rewritten version rather than the dev server's. If you would rather not install bun, the Dockerfile is the alternative. It builds the site and serves it with nginx on port 80, with a HEALTHCHECK that runs nginx -t -q every 30 seconds. The build stage skips the puppeteer browser download, so this path produces the site and not the PDF. ## What the article is not, and where it stops being useful This is a narrative, and narratives have boundaries. The README describes the research as assembling many sources of varying quality, and the output is one continuous explanation. That is the strength and the limit. There is no per-architecture reference, no versioned API to track, and no changelog of corrections: recent releases returned nothing, and the repository has no release cadence to speak of. If you need the current behaviour of a specific kernel version or a specific instruction set, this is the wrong artifact. Go to the vendor manuals and the kernel source. The repository is also not a template for a documentation site in the general case. It is one article with a custom Astro setup, a banner in public/github-images, and a PDF generator that the container build explicitly disables. Nothing in the README describes rollback, versioning of the prose, or a stable interface for downstream consumers. If you fork it to publish your own explainer, you are adopting the author's structure rather than a maintained framework. Finally, the README's own recommendation is to read chapter 3 if you are in a hurry. That is a sign the chapters are meant to be read in sequence and that skipping ahead costs you the thread. Readers who want to jump straight to a specific mechanism will find the format less convenient than a wiki. ## How it compares with the resources it was written to replace The obvious alternative is the material the README describes sifting through: scattered blog posts, forum answers and course notes, each covering one layer. Those sources are often more current and more granular. A kernel mailing list thread will tell you exactly how a syscall entry point changed; this article will not. What the scattered sources lack is the connective tissue, which is the specific thing the author set out to provide after finding information that conflicted. A second alternative is a conventional systems textbook, which covers the same ground with exercises, citations and an editorial process. The difference is approach rather than subject. A textbook is organized for a course and verified by reviewers; this is organized as one person's path from confusion to a working model, and the README is candid that the notes came from sources of varying quality. If you want citations you can follow, the textbook wins. If you want the shortest route to a mental model that holds together end to end, the article's single-narrative approach is the reason to pick it. A third alternative is the Linux source tree itself. It is authoritative and free, and it is also unreadable as an introduction. The article's value is not that it contains information the source tree lacks, but that it orders that information for someone who has never seen the whole path. ## Maintenance, licence and what a fork costs you The repository is not archived, and the last push was on 2026-09-16, so the source is recent. That does not make it a maintained library: there are no releases, the version field reads 0.0.1, and the package is private. Treat the dependency updates as the only recurring cost. Astro, @astrojs/mdx, @astrojs/vercel, shiki, puppeteer and the rehype plugins all move, and bun.lock pins what the build expects. A fork that goes untouched for a year will need bun install to resolve newer versions or a deliberate decision to stay pinned. The licence is MIT, which is permissive and permits reuse and redistribution provided the copyright notice and permission notice are kept. The repository ships a LICENSE file at the top level. The prose itself is the author's work, so a fork that republishes the chapters is redistributing content, not just code, and attribution is the practical question to settle. This is a description of the licence terms, not legal advice; if you plan to republish commercially, read the LICENSE file and the attribution the README already gives to @kognise and @hackclub. Operationally, the cheapest way to run your own copy is the Dockerfile. It needs no bun on the host, exposes port 80, and the health check is nginx -t -q. The PDF generator is the one piece that does not come along for free. ## Conclusion Read it if you have gaps between syscalls, ELF and the kernel and want one continuous narrative; self-host it if you want a local copy of cpu.land. Skip it if you need a reference manual, per-architecture detail, or a maintained library with versioned releases. Before adopting the repository as a base, open pdfgen.js and check whether puppeteer is on your path, since the Dockerfile sets PUPPETEER_SKIP_DOWNLOAD=true and the PDF step is not part of the image build. ## FAQ ### How do I run Putting the "You" in CPU locally? Clone the repository and install dependencies with bun install --frozen-lockfile, then run bun run dev to start the Astro dev server. The README itself points readers at the hosted site at cpu.land instead of giving install steps. ### Is Putting the "You" in CPU a program or a website? It is a website. The repository is an Astro site whose content is written in MDX, and package.json marks the package private with version 0.0.1, so nothing is published for installation as a dependency. ### What licence does Putting the "You" in CPU use? MIT, with a LICENSE file at the top level of the repository. The README credits @kognise and @hackclub as the authors. ### Can I build a PDF of Putting the "You" in CPU? The repository contains pdfgen.js and lists puppeteer and jsdom as devDependencies, but the Dockerfile sets PUPPETEER_SKIP_DOWNLOAD=true, so the container build produces the site without a browser. The README does not document the PDF workflow. ## Sources - [hackclub/putting-the-you-in-cpu on GitHub](https://github.com/hackclub/putting-the-you-in-cpu) - [Issues](https://github.com/hackclub/putting-the-you-in-cpu/issues) - [License: MIT](https://github.com/hackclub/putting-the-you-in-cpu/blob/main/LICENSE) - [Project website](https://cpu.land) - [README](https://github.com/hackclub/putting-the-you-in-cpu/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hackclub-putting-the-you-in-cpu