<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en">
    <title>Anton Vasiljev - keebs</title>
    <subtitle>Trivial things about software development</subtitle>
    <link rel="self" type="application/atom+xml" href="https://antono.info/en/tags/keebs/atom.xml"/>
    <link rel="alternate" type="text/html" href="https://antono.info"/>
    <generator uri="https://www.getzola.org/">Zola</generator>
    <updated>2026-06-25T13:34:21+00:00</updated>
    <id>https://antono.info/en/tags/keebs/atom.xml</id>
    <entry xml:lang="en">
        <title>One flake to build them all: managing 5 split keyboards with Nix</title>
        <published>2026-06-25T13:26:52+00:00</published>
        <updated>2026-06-25T13:34:21+00:00</updated>
        
        <author>
          <name>Unknown</name>
        </author>
        
        <link rel="alternate" type="text/html" href="https://antono.info/en/blog/2026/06/25/keebs-nix/"/>
        <id>https://antono.info/en/blog/2026/06/25/keebs-nix/</id>
        
        <content type="html" xml:base="https://antono.info/en/blog/2026/06/25/keebs-nix/">&lt;h2 id=&quot;my-story-with-mechanical-keyboards&quot;&gt;My story with mechanical keyboards&lt;/h2&gt;
&lt;p&gt;It started in December 2022. I bought a Dao — a 42-key column-staggered split running &lt;a rel=&quot;external&quot; href=&quot;https://zmk.dev&quot;&gt;ZMK&lt;/a&gt; — and that was it. I was hooked!&lt;/p&gt;
&lt;p&gt;There&#39;s something about a split keyboard that rewires how you think about typing. Your hands stop reaching. Layers replace the number row, the symbol row, the navigation cluster. The keymap becomes a personal artifact you tune for months. And once you&#39;ve tuned one, you want another board to tune.&lt;/p&gt;
&lt;p&gt;Three and a half years later I own &lt;strong&gt;five&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Ergonaut One — column-stagger split (Seeeduino XIAO BLE + shield)&lt;/li&gt;
&lt;li&gt;HolySwitch TK44 — unibody monosplit (custom board)&lt;/li&gt;
&lt;li&gt;Mriya46 — column-stagger split (two custom nRF52840 boards)&lt;/li&gt;
&lt;li&gt;Dao — the one that started it, 42-key split (+ ZMK Studio)&lt;/li&gt;
&lt;li&gt;Charybdis Mini — 34-key split with a trackball Five keyboards is wonderful.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Five keyboards is also a configuration management problem.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://antono.info/en/blog/2026/06/25/keebs-nix/489949bc-5358-4de4-b946-2b2e2012ef72.jpeg&quot; alt=&quot;&quot; /&gt;&lt;/p&gt;
&lt;p&gt;Every ZMK keyboard wants its own &lt;code&gt;zmk-config&lt;/code&gt; repo. The community workflow is well-paved and, honestly, friendly to beginners:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Fork someone&#39;s &lt;code&gt;*-zmk-config&lt;/code&gt; repo on GitHub.&lt;/li&gt;
&lt;li&gt;Edit the &lt;code&gt;.keymap&lt;/code&gt; file.&lt;/li&gt;
&lt;li&gt;Push.&lt;/li&gt;
&lt;li&gt;GitHub Actions reads &lt;code&gt;build.yaml&lt;/code&gt;, spins up a runner, clones Zephyr + ZMK, compiles, and uploads &lt;code&gt;.uf2&lt;/code&gt; artifacts.&lt;/li&gt;
&lt;li&gt;Download the zip, unzip, flash each half.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;This workflow is beginner friendly but have some problems:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Every tweak — even fixing one keycode — means commit → push → wait for the runner to cold-clone Zephyr → download zip → unzip → flash. Minutes of round-trip for a one-character edit.&lt;/li&gt;
&lt;li&gt;Five repos, five forks, five histories. Each keyboard a separate fork, each drifting from its upstream, each with its own quirks. Aligning all five keymaps to the same layout meant five PRs in five places.&lt;/li&gt;
&lt;li&gt;Not reproducible. &quot;It built last month&quot; is not the same as &quot;it builds the same bytes today.&quot; Upstream ZMK &lt;code&gt;main&lt;/code&gt; moves, runners change, and one day your config simply doesn&#39;t compile anymore. That last point bit me. ZMK &lt;code&gt;main&lt;/code&gt; migrated to Zephyr&#39;s **Hardware Model v2**, which renamed the very boards my configs depend on (seeeduino_xiao_ble → xiao_ble, nice_nano_v2 → nice_nano). Configs that built fine suddenly didn&#39;t. The CI-fork workflow has no answer for &quot;pin the whole world.&quot;&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;keebs-nix-one-flake-to-build-them-all&quot;&gt;keebs-nix: one flake to build them all&lt;/h2&gt;
&lt;p&gt;Nix does have an answer for &quot;pin the whole world.&quot; So I built &lt;a rel=&quot;external&quot; href=&quot;https://github.com/antono/keebs-nix&quot;&gt;keebs-nix&lt;/a&gt; — a single, self-contained flake that builds firmware for all five keyboards, on top of &lt;a rel=&quot;external&quot; href=&quot;https://github.com/lilyinstarlight/zmk-nix&quot;&gt;zmk-nix&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;Each keyboard&#39;s complete ZMK config — &lt;code&gt;west.yml&lt;/code&gt;, &lt;code&gt;boards/&lt;/code&gt;, keymaps, &lt;code&gt;.conf&lt;/code&gt; — is &lt;strong&gt;vendored&lt;/strong&gt; verbatim into this repo. No forks, no external config repos, no submodules. The flake has exactly two inputs: &lt;code&gt;nixpkgs&lt;/code&gt; and &lt;code&gt;zmk-nix&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;what-the-flake-does&quot;&gt;What the flake does&lt;/h2&gt;
&lt;p&gt;Builds everything with one command.&lt;/p&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color-scheme: light dark; color: light-dark(#24292E, #E1E4E8); background-color: light-dark(#FFFFFF, #24292E);&quot; &gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: light-dark(#6F42C1, #B392F0);&quot;&gt;nix&lt;/span&gt;&lt;span style=&quot;color: light-dark(#032F62, #9ECBFF);&quot;&gt; build&lt;/span&gt;&lt;span style=&quot;color: light-dark(#6A737D, #6A737D);&quot;&gt;               #&lt;/span&gt;&lt;span style=&quot;color: light-dark(#6A737D, #6A737D);&quot;&gt; all firmware → ./result (combined .uf2 dir)&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: light-dark(#6F42C1, #B392F0);&quot;&gt;nix&lt;/span&gt;&lt;span style=&quot;color: light-dark(#032F62, #9ECBFF);&quot;&gt; build&lt;/span&gt;&lt;span style=&quot;color: light-dark(#032F62, #9ECBFF);&quot;&gt; .#dao&lt;/span&gt;&lt;span style=&quot;color: light-dark(#6A737D, #6A737D);&quot;&gt;         #&lt;/span&gt;&lt;span style=&quot;color: light-dark(#6A737D, #6A737D);&quot;&gt; or just one&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The output is a single directory with stable, human-readable filenames — no hunting through &lt;code&gt;zmk_left.uf2&lt;/code&gt; artifacts wondering which board they came from:&lt;/p&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color-scheme: light dark; color: light-dark(#24292E, #E1E4E8); background-color: light-dark(#FFFFFF, #24292E);&quot; &gt;&lt;code data-lang=&quot;plain&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;ergonaut_one_left.uf2   ergonaut_one_right.uf2   ergonaut_one_settings_reset.uf2&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;tk44.uf2&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;mriya46_left.uf2        mriya46_right.uf2        mriya46_settings_reset.uf2&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;dao_left.uf2            dao_right.uf2            dao_studio_left.uf2  ...&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;charybdis_mini_left.uf2 charybdis_mini_right.uf2 charybdis_mini_settings_reset.uf2&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Flashes from the command line.&lt;/p&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color-scheme: light dark; color: light-dark(#24292E, #E1E4E8); background-color: light-dark(#FFFFFF, #24292E);&quot; &gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: light-dark(#6F42C1, #B392F0);&quot;&gt;nix&lt;/span&gt;&lt;span style=&quot;color: light-dark(#032F62, #9ECBFF);&quot;&gt; run&lt;/span&gt;&lt;span style=&quot;color: light-dark(#032F62, #9ECBFF);&quot;&gt; .#flash-dao&lt;/span&gt;&lt;span style=&quot;color: light-dark(#6A737D, #6A737D);&quot;&gt;        #&lt;/span&gt;&lt;span style=&quot;color: light-dark(#6A737D, #6A737D);&quot;&gt; prompts for left, then right&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: light-dark(#6F42C1, #B392F0);&quot;&gt;nix&lt;/span&gt;&lt;span style=&quot;color: light-dark(#032F62, #9ECBFF);&quot;&gt; run&lt;/span&gt;&lt;span style=&quot;color: light-dark(#032F62, #9ECBFF);&quot;&gt; .#flash-tk44&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: light-dark(#6F42C1, #B392F0);&quot;&gt;nix&lt;/span&gt;&lt;span style=&quot;color: light-dark(#032F62, #9ECBFF);&quot;&gt; run&lt;/span&gt;&lt;span style=&quot;color: light-dark(#032F62, #9ECBFF);&quot;&gt; .#flash-dao-reset&lt;/span&gt;&lt;span style=&quot;color: light-dark(#6A737D, #6A737D);&quot;&gt;  #&lt;/span&gt;&lt;span style=&quot;color: light-dark(#6A737D, #6A737D);&quot;&gt; settings reset, built on nice_nano_v2&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Renders keymap diagrams. Every keyboard&#39;s README embeds a layout SVG generated by &lt;a rel=&quot;external&quot; href=&quot;https://github.com/caksoylar/keymap-drawer&quot;&gt;keymap-drawer &lt;/a&gt;straight from the vendored keymap:&lt;/p&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color-scheme: light dark; color: light-dark(#24292E, #E1E4E8); background-color: light-dark(#FFFFFF, #24292E);&quot; &gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: light-dark(#6F42C1, #B392F0);&quot;&gt;nix&lt;/span&gt;&lt;span style=&quot;color: light-dark(#032F62, #9ECBFF);&quot;&gt; run&lt;/span&gt;&lt;span style=&quot;color: light-dark(#032F62, #9ECBFF);&quot;&gt; .#draw-keymaps&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;img src=&quot;https://antono.info/en/blog/2026/06/25/keebs-nix/d9d57029-2886-4492-b7db-c6b844a8f01b.png&quot; alt=&quot;&quot; /&gt;&lt;/p&gt;
&lt;p&gt;So the docs can&#39;t drift from the firmware — they&#39;re parsed from the same &lt;code&gt;.keymap&lt;/code&gt; file the build uses.&lt;/p&gt;
&lt;h2 id=&quot;why-nix-is-the-right-tool-for-this&quot;&gt;Why Nix is the right tool for this&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Reproducibility, for real.&lt;/strong&gt; The vendored west.yml files pin ZMK to v0.3-branch plus Zephyr 3.5 — the known-good, pre-HWMv2 revision. That sidesteps the board-rename breakage entirely. The build that works today produces identical bytes next year. Nix doesn&#39;t try to be reproducible; it&#39;s the whole premise.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;One shared dependency fetch.&lt;/strong&gt; All five configs ship a byte-identical west.yml, so instead of each keyboard cold-cloning multi-gigabyte Zephyr and ZMK trees, a single fixed-output derivation fetches the West deps once and every keyboard reuses it. One hash in flake.nix covers the whole fleet. The fetch even does a shallow narrow depth-1 update so it pulls minutes of data instead of hours on a slow link — and survives GitHub&#39;s flaky HTTP/2 stream resets on the big clone.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Fast local change/flash cycle.&lt;/strong&gt; Edit a keymap, run nix build, run nix flash. No push, no runner, no zip. The deps are cached, so rebuilds are quick. This is the single biggest day-to-day win over the CI-fork loop.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Adding a keyboard is one line.&lt;/strong&gt; New boards drop into the keyboards directory and a single entry in the firmwareOutputs map. The bundle-copy logic globs each build&#39;s actual uf2 outputs and renames them generically, so splits and single-firmware boards both just work — no hardcoded filenames.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Self-contained.&lt;/strong&gt; Because every config is vendored rather than referenced, there&#39;s nothing to go stale out from under me. The Dao even vendors its board definition from the ergonautkb ZMK module rather than pulling it via west.yml, so it&#39;s as self-contained as the rest.&lt;/p&gt;
</content>
        
    </entry>
</feed>
