I run my own model, and part 6 of this series covers that side for the laptop: llama.cpp, a quantized GGUF file, an OpenAI-compatible API on a port. The two boxes on my tailnet run a different engine for a much larger model. This post is about the layer above both of them, the program you actually type into. That layer is the one I understood last, and it is the one I ended up configuring hardest.

Three harnesses went through the machine. Each left a config file and a directory of session logs, so everything below is something I can point at on disk rather than remember. The hostnames are my own names for my machines, and the config excerpts use them too.

What a harness decides

For a while I treated the harness as a product: you install it, it has a model behind it, you talk to it. Under that model of it, changing harnesses means changing what the AI can do, which is mostly false.

A harness is the thing that decides what goes into the context window, which tools exist at all, what happens when a tool call fails, how much of your machine the model may touch, and whether the conversation is summarized before it hits the limit. The weights are the part you usually do not control. Everything in that list is the part you do.

The first place that landed for me was a fourteen line file. Here is the entire model configuration I used with Pi:

{
  "providers": {
    "llama-server": {
      "baseUrl": "http://127.0.0.1:8900/v1",
      "api": "openai-completions",
      "apiKey": "local",
      "models": [
        {
          "id": "Ornith",
          "contextWindow": 131072,
          "maxTokens": 4096
        }
      ]
    }
  }
}

Two of those lines are hardware decisions wearing model clothes. contextWindow and maxTokens are a budget: how much prompt the model may hold, and how much room to leave for the answer. On a ThinkPad T480 serving a 35B model at Q4_K_M from CPU kernels, that budget is set by the machine, not by the model card, and a harness that never asks you for it is guessing on your behalf.

Three endpoints, three config files

Before I had picked a harness I had already put the model behind an HTTP URL. Three endpoints, all mine or on my tailnet, two engines behind them, all speaking the same OpenAI-compatible API:

• amal, the ThinkPad I use every day, serving Ornith-1.5-35B-Uncensored-Q4_K_M.gguf on port 8901 through the ik_llama.cpp fork, built with all CPU variant kernels. Port 8901 rather than 8900 because SearXNG owns 8900 on that machine.
• gimel on port 8080, serving peculiar-ragdoll/Cyber-Tiel-Coder-35B-A3B-GGUF-MTP over llama.cpp.
• gimel2 on port 8080, running Strata, an MIT licensed inference engine built around one model, Qwen3.8-Flash-Next. The quant my current configuration names is IQ3_S from the ISTA-DASLab GSQ-RCO files; an earlier one named Unsloth's UD-IQ4_XS.

Once the model is a URL, a harness is a client, and a client is a config file. Here is the same decision in OpenCode:

"gimel2": {
  "name": "gimel2",
  "npm": "@ai-sdk/openai-compatible",
  "options": {
    "baseURL": "http://gimel2.tail5481a4.ts.net:8080/v1"
  },
  "models": {
    "qwen3.8-flash-next": {
      "name": "Qwen3.8-Flash-Next",
      "modalities": {
        "input": ["text", "image"],
        "output": ["text"]
      }
    }
  }
}

And the same decision again in the flake, as a patch the harness reads on activation:

{
  id = "llm-pi-ai";
  name = "@deepseek-ai/dsh-llm-pi-ai";
  config = {
    providers = {
      gimel2 = {
        displayName = "gimel2";
        apiKeyEnv = "GIMEL2_API_KEY";
        api = "openai-completions";
        baseURL = "http://gimel2.tail5481a4.ts.net:8080/v1";

Three syntaxes, one decision. That is why changing harnesses cost me an afternoon each time instead of a rebuild of how I work.

Strata uses parts of llama.cpp and ggml, so the engine on gimel2 and the engine on the laptop share ancestry, and both end at the same kind of URL. The hardware is uneven, and the API is what makes it one thing to configure against.

Which engine sits behind each of those URLs, which quantization it is served at, and what that costs in tokens per second on the three machines involved is a post of its own: Getting a 125B model onto a 12 GB card. From the harness side the endpoints differ in speed, not in protocol, and that is the only part that matters there.

Pi: one provider block and two packages

Pi (source, MIT) is deliberately minimal. No sub-agents, no plan mode, no permission popups, no background bash in the core; those are things you build or install as packages. What it gives you instead is control of the context: a small system prompt, AGENTS.md loaded from its own config directory and the directory tree, and sessions stored as a tree in one file so you can branch back to any earlier point.

My setup was the provider block above plus two packages, pi-web-access and pi-mcp-adapter, with telemetry switched off. Nothing else.

What it taught me came out of its session logs, which are plain JSONL. The largest session in the directory is the first attempt at this website. It ran 297 messages and 145 tool calls, and the split is the number worth knowing: 75 bash, 32 edit, 26 write, 12 read. Half the session was the model checking what the shell would actually do. Reading that ratio is the first harness skill I developed, and it says more about a run than the transcript does.

Pi's lack of opinions is honest, but it means everything above the primitives is yours to build, and building it is exactly the work a small local model is worst at.

OpenCode: providers, plugins and compaction

I had downloaded OpenCode once before and put it down again without getting anywhere with it. The time I actually used it is the time that produced the config below, and it is the harness where I spent the most tokens: 16,028,123 input and 2,659,633 output on the ledger, for a recorded cost of $0.04, because nearly all of it went to my own endpoints.

OpenCode ships with the machinery Pi leaves out: sub-agents, plan mode, a permission system, LSP integration. My config points it at three local providers, adds three MCP servers (one of them nix run nixpkgs#mcp-nixos, for NixOS option lookups), sets "bash": "ask" and "edit": "allow", and installs six plugins:

"plugin": [
  "oh-my-openagent",
  "opencode-skillful",
  "opencode-supermemory",
  "opencode-notifier",
  "opencode-scheduler",
  "opencode-dynamic-context-pruning"
],
"compaction": {
  "auto": true,
  "prune": false,
  "reserved": 10000
}

The last two of those are the local-model adaptations, and they are the part of the config I would defend. A context pruning plugin and a compaction step that holds 10,000 tokens back are not there to make the agent clever. They are there because with a local model, context is not a bill, it is minutes of my own hardware, and a session that drags its whole history is slow in a way that stops you working.

The plan plugin keeps a work ledger at ~/.omo/boulder.json with named plans, an agent name and elapsed time. The entry for this website records 95 minutes for the plan that produced the first commit. The same ledger and the session database show the shape of that run: a parent session, then short-lived children doing the reading, one of which took 905,542 input tokens to produce 11,678 output tokens of summary. Sub-agents multiply context faster than they multiply useful work, and when the model is local the price arrives as waiting rather than as money.

DeepSeek Harness: installed by the flake

DeepSeek Harness is what I run now, and it won on the one thing the other two did not offer: it installs as a Nix flake input, so the harness is part of the system I rebuild rather than something I installed once with npm.

programs.dsh = {
  enable = true;
  profiles.web = {
    bundles = [
      pkgs.dsh.bundles.base
      pkgs.dsh.bundles.web-app
      pkgs.dsh.bundles.web-ui
    ];

The provider is the patch quoted above, so every activation rewrites it, and the API key it reads is the string "x", set in environment.sessionVariables. The endpoint does not authenticate, because reachability is the tailnet, and Strata's own documentation says any key and any model name will be accepted. I would rather declare a dummy than keep a secret in a file that is not secret.

The two timeouts in ~/.dsh/settings.yaml are both 900,000 ms. Fifteen minutes of patience is arithmetic rather than caution: gimel2 reads a prompt at 997 tokens per second, so a 30,000 token first message costs about half a minute before the first token of the answer appears, and an agent run stacks several of those. It also answers one request at a time unless you turn on batching. A harness with a shorter default will kill work that was going fine.

agent-default-model:
  provider: gimel2
  model: qwen3.8-flash-next-iq3_s

The practical difference from the other two is recovery. A fresh machine, or a wiped home directory, gets the model endpoints, the timeouts and the default model back from nixos-rebuild switch. There is nothing to re-download and no key to go looking for.

What stays on my machines

Worth stating precisely, because "local AI" gets used loosely:

• The quantized model files sit on hardware I own, and the engine on the laptop is built from source by a Nix expression I wrote.
• The endpoints are tailnet hostnames. Nothing is listening on the WAN, and the authentication is the WireGuard interface rather than a token.
• Prompts, tool output and session history stay on my machines. The session logs are the reason this post exists, and no third party has a copy of them.
• The harness configuration is in the same git repository as the rest of the system config.

One boundary I would rather state than gloss over: the OpenCode config also carried the free hosted models that provider ships with, and I used them for tasks the laptop could not carry. Those sessions are separable in the same database, and the rule I would keep is to know exactly which ones they were rather than to pretend the setup is all local.

This repository, three harnesses

This repository is the cleanest test case, because all three touched it or touched a version of it. Pi wrote the first attempt, a Next.js app. OpenCode rebuilt the idea, then dropped the framework, leaving a directory with index.html, style.css and app.js, and then ran the plan that produced this repo. DeepSeek Harness has been writing it since. The repo does not care which program made a commit, and that is the point: the parts that made it swappable were decided before any harness was chosen.

Further reading

• Pi and its source: the minimal harness, and the page listing what it deliberately does not ship.
• OpenCode: the config schema my provider, plugin and compaction blocks are written against.
• DeepSeek Harness: the plugin architecture and the NixOS module I install it through.
• Strata: the inference engine on the two tailnet boxes, and the page that explains how a 125B mixture of experts is split across GPU, RAM and SSD.
• ik_llama.cpp: the fork behind the laptop endpoint.

Part 6 of the NixOS series covers how the model is wired into my system: the build, the service, the OpenAI-compatible API. It does not cover the part I actually spend time on, which is choosing the engine, the quantization and the context length for a specific piece of hardware. That choice is where the speed comes from, and it is the part I can now show you numbers for.

Weights plus KV cache

One line decides whether a model runs at all:

weights (parameters x bits per weight) + KV cache (context) <= RAM / VRAM

Quantization buys you the first term. A model ships as 16 bit numbers; storing them at 4 or 5 bits divides the memory by three or four with little visible loss. The scheme I recommend to anyone, and the one both 35B models run, is Q4_K_M, around 4.8 bits per weight: most of what Q8_0 gives at half the size. The one exception is Qwen3.8-Flash-Next at IQ3_S, which is a much larger model whose experts can afford a tighter quantization. Below Q3_K_M quality falls off fast enough that the saved gigabytes usually cost more than they save.

The KV cache is the second term and the one people forget. When the model reads a token it keeps that token's keys and values in memory, because recomputing them at every step would mean re-reading the whole conversation each time. That store is the cache, and it grows with the context, which is why the context window is a physical limit rather than a setting: attention lets each token interact with every other one, so doubling the context roughly quadruples that work. Mine is stored at q8_0, eight bits per value instead of the sixteen a full-precision cache uses, which halves the memory the same window costs. Quantizing the cache is a separate decision from quantizing the weights and worth making on purpose: the weights decide what the model knows, the cache decides how much of the conversation it can hold.

Prefill and decode

Prefilling processes the whole prompt in parallel, which is what a graphics card is good at. Decoding emits one token at a time and is limited by memory bandwidth. On my machines the ratio between the two is around ten to one, so a harness that sends long prompts is paying a different cost than a chat that shows a short answer. This is the reason an agent loop feels nothing like a chat window pointed at the same model.

What each box runs

Both boxes are an i9-13900 with an RTX 3060 holding 12 GB of VRAM and 64 GB of RAM. The laptop is a ThinkPad T480 with an i7-8650U and 32 GB. These are readings taken while working, not a benchmark run:

Every row runs its cache at q8_0. The last two rows are the same machine, the same card and the same model at the same 256k context, with only the engine changed. Decode went from 12 tokens per second to 49, and from 6 with that context nearly full to 45. Prefill went from 55 to 997. That is the whole argument for the rest of this post. gimel is next on the list.

How a 125B model fits on a 3060

Qwen3.8-Flash-Next is a mixture of experts: 24,576 of them, and a single token only routes through about 10. That is what makes the model cheap per token and expensive to store. Strata is an MIT licensed inference engine built around that shape, and the way it makes the model fit is a placement decision rather than a smaller model:

• The few thousand experts used most often sit on the graphics card, which is the only part that has to be fast.
• All of them sit in the 64 GB of system RAM, and the processor works on the ones the card is not holding at the same time.
• A 29 GB lookup table stays on the SSD and is only read when an expert is needed that RAM is not holding.
• A small draft model guesses the next few words and the big model checks them in one pass, which the project measures at 1.6 to 1.8 times faster for the same answer.

The published figures are for an RTX 5070: 53 tokens per second of decode and 1,620 per second reading a prompt at IQ3_S. My card is a 3060 with 12 GB, and the table above is what that actually gives. The CPU matters more than it looks in that number, because the processor is not just orchestrating, it is holding part of the model.

The same reasoning explains the row above it. A 35B model at Q4_K_M is around 21 GB with a 32k context, which does not fit in 12 GB of VRAM either, so llama.cpp splits it between the card and RAM and runs it there. The difference is that a dense model has no experts to place selectively, so the split costs more.

The laptop throttles

10 tokens per second out of a CPU-only 35B is what an i7-8650U gives, and the ceiling there is heat rather than compute. The AVX2 load throttles the chip, so the rate you see is a sustained thermal number, not the one a short benchmark prints. That is why the laptop runs the small model and answers quickly about small things, and anything that needs a large context goes to a box with a card in it.

Context length has to match on both sides

The expensive part of running an agent locally is not the model, it is that a harness resends its instructions, its tool catalogue and its history on every step. In measurements I took for a session I ran in August 2026, a trivial task cost 14,700 input tokens because about 25 tool schemas go back with every step. In the same set of runs, a small model at 2.2 tokens per second on CPU never finished an agent turn at all.

Two rules came out of that, and both are configuration rather than modelling:

• The context a harness declares must match the context the server was started with. If the harness thinks it has more room than the server allocated, the middle of the prompt is dropped silently.
• Prefill is what an agent pays for, so a fast prefill changes what is pleasant to use before it changes what the model can reason about. That is the number that moved most when I changed engine: 55 to 997 tokens per second.

A Robotech formation from the same material

Writing this down for other people is what made it stick. I gave a Robotech formation, Des LLM aux agents locaux, built from the same material in three parts: what happens inside a model (tokens, embeddings, attention as queries, keys and values, why the KV cache makes context expensive), how to run one yourself (llama.cpp and GGUF, the quantization table, sizing weights plus KV cache against a machine, then a live llama-server), and what an agent harness adds on top (the loop, function calling, MCP, skills, AGENTS.md, and pointing DeepSeek Harness at a local endpoint).

The exercise is the part I am happiest with: three machines, one with no GPU, one with an RTX 3060 and 12 GB, one with 8 GB of unified memory, and the task is to pick model, quantization and context for each and justify it in one line against the budget. The deck, the demo scripts and the model landscape slide are in the Robotech Formation repository, CC BY-NC-SA 4.0, with the transformer figures from 3Blue1Brown.

Further reading

• Strata: the engine, and its model and size page for what fits in how much RAM.
• ik_llama.cpp: the fork I build on the laptop, with the CPU variant kernels part 6 explains.
• Formation Robotech: Des LLM aux agents locaux: the deck this post is a written version of.
• 3Blue1Brown on attention: the explanation the first part of the formation is built on.

lili is the device detection project I worked on during the research internship: several probes (wifi, bluetooth, lora, gps) listen for objects nearby and publish what they hear to an MQTT bus. I worked on the wifi module, and the change I got the most out of is a deletion. The module used to reconfigure a wireless interface by starting another program. Two commits in July 2026 removed that habit. The code sits in the university GitLab and is not public, so everything quoted below is quoted from it.

The history in that repository goes back to 2021, so the module I joined had a few years of decisions in it, and calling iw was a reasonable one. It is quick to write and easy to read. It is also a subprocess, a PATH lookup, a dependency on a program being installed on the probe, and an exit status as the only way to find out what went wrong.

What the module does

It creates a monitor interface (mon0 on phy0 by default), captures on it with pcap, and checks that the datalink is DLT_IEEE802_11_RADIO before trusting anything. Each frame goes through a radiotap iterator and then an 802.11 management frame parser, which keeps two linked lists: devices and access points, each holding a MAC and the last signal level seen. Three MQTT topics carry the result. wifi/raw gets the frame itself, wifi/dev/new, upd and del get the objects, and wifi/net/link gets a pair of ids that were seen talking.

The radio does not stay put. A detached thread walks a FIFO of 31 channels across 2.4 and 5 GHz, sleeping 4 seconds between switches, so a full sweep takes just over two minutes.

The hot path was a subprocess

That thread called set_channel every four seconds. This is what set_channel was:

int set_channel(const char *iface, unsigned char chan)
{
    pid_t child;
    int status = 0;
    char str_chan[8] = {0};
    if (chan < 1 || chan > 140) {
        fprintf(stderr,
            "Tentative d'utiliser le channel WiFi %hhu, "
            "non-existant.\n",
            chan);
        return -1;
    }
    snprintf(str_chan, sizeof str_chan, "%hhu", chan);

    if (veryverbose) {
        printf("Execution de `iw dev %s set channel %s`\n", iface,
               str_chan);
    }
    if ((child = fork()) == 0) {
        execlp("iw", "iw", "dev", iface, "set", "channel", str_chan,
               NULL);
    }
    waitpid(child, &status, 0);
    return WEXITSTATUS(status);
}

A fork, an exec of whatever iw is first on PATH, a waitpid, and a WEXITSTATUS. Fifteen times a minute, about 900 times an hour, to hand the kernel something it exposes as a single netlink message.

Setup did it three more times

Bringing the capture interface up was the same pattern, repeated:

if ((child = fork()) == 0) {
        PERR_CALL_L0(execlp("iw", "iw", "phy", physical_iface,
                    "interface", "add", monitor_iface, "type",
                    "monitor", NULL));
    }
    waitpid(child, NULL, 0); // TODO: verifier echec

    for (char **iface = wifi_ifaces; *iface != NULL; iface++) {
        if (verbose) {
            printf("Desactivation de l'interface %s\n", *iface);
            printf("`ip link set %s down`\n", *iface);
        }
        if ((child = fork()) == 0) {
            PERR_CALL_L0(execlp("ip", "ip", "link", "set", *iface,
                        "down", NULL));
        }
        waitpid(child, NULL, 0);
    }

    if (verbose) {
        printf("Activation de l'interface %s\n", monitor_iface);
        printf("`ip link set %s up`\n", monitor_iface);
    }
    if ((child = fork()) == 0) {
        PERR_CALL_L0(execlp("ip", "ip", "link", "set", monitor_iface,
                    "up", NULL));
    }
    waitpid(child, NULL, 0);

Five execlp sites in the file. The error handling was a comment: waitpid(child, NULL, 0); // TODO: verifier echec. The list of interfaces to bring down was also hardcoded as {"wlan0", NULL}, which stops being funny the first time someone runs a probe with a USB adapter, because those come up named after their MAC. The config in the repository points at one such wlx... interface.

First commit: ask the kernel which interfaces exist

NL80211_CMD_GET_INTERFACE sent with NLM_F_DUMP | NLM_F_REQUEST gives one netlink message back per wireless interface. libnl hands each one to a callback, and the callback reads NL80211_ATTR_IFNAME and strdups it into a NULL-terminated array capped at 5 entries. That is the whole trick, and it replaced a hardcoded name.

The commit is 160 lines, and a suspicious number of them are socket boilerplate: allocate, genl_connect, genl_ctrl_resolve, allocate a message, install the callback, send, receive, free. The second commit pulled all of that into one place.

Second commit: the state changes go through netlink as well

437 insertions and 262 deletions across four files. It starts with a session object, opened once in main_init and closed in main_cleanup:

struct nl80211_session {
    struct nl_sock *sock;
    int id;    // id de la famille nl80211
};

static int nl80211_session_init(struct nl80211_session *s)
{
    int ret;

    s->sock = nl_socket_alloc();
    if (!s->sock) {
        fprintf(stderr, "Impossible d'allouer un socket netlink\n");
        return -1;
    }

    ret = genl_connect(s->sock);
    if (ret < 0) {
        fprintf(stderr, "Impossible de connecter le socket netlink (code %d)\n", ret);
        nl_socket_free(s->sock);
        return ret;
    }

    ret = genl_ctrl_resolve(s->sock, "nl80211");
    if (ret < 0) {
        fprintf(stderr, "Famille nl80211 non trouvee (code %d)\n", ret);
        nl_socket_free(s->sock);
        return ret;
    }
    s->id = ret;

    return 0;
}

Five nl80211 commands cover everything the module needs:

• GET_INTERFACE, dumped, to list what is on the machine.
• GET_WIPHY, dumped, to turn a name like phy0 into the u32 index nl80211 wants.
• NEW_INTERFACE with WIPHY, IFNAME and IFTYPE set to NL80211_IFTYPE_MONITOR.
• DEL_INTERFACE with an ifindex, called at startup in case mon0 already exists and again in main_cleanup.
• SET_WIPHY with WIPHY_FREQ and CHANNEL_WIDTH, which is the one the hopping thread runs every four seconds.

They all have the same shape:

static int nl80211_create_interface(struct nl80211_session *s, int wiphy_idx,
                                    const char *ifname, enum nl80211_iftype type)
{
    struct nl_msg *msg;
    int ret;

    msg = nlmsg_alloc();
    if (!msg) return -1;

    genlmsg_put(msg, NL_AUTO_PORT, NL_AUTO_SEQ, s->id, 0, 0,
                NL80211_CMD_NEW_INTERFACE, 0);

    NLA_PUT_U32(msg, NL80211_ATTR_WIPHY, wiphy_idx);
    NLA_PUT_STRING(msg, NL80211_ATTR_IFNAME, ifname);
    NLA_PUT_U32(msg, NL80211_ATTR_IFTYPE, type);

    ret = nl_send_auto(s->sock, msg);
    if (ret < 0) {
        fprintf(stderr, "nl80211_create_interface: send error %d\n", ret);
        nlmsg_free(msg);
        return ret;
    }

    ret = nl_recvmsgs_default(s->sock);
    if (ret < 0)
        fprintf(stderr, "nl80211_create_interface: recv error %d\n", ret);

    nlmsg_free(msg);
    return ret;

nla_put_failure:
    nlmsg_free(msg);
    return -NLE_NOMEM;
}

Two things in there are worth knowing before you write your own. NLA_PUT_U32 is a macro that jumps to a label called nla_put_failure when an attribute does not fit, which is why every helper ends with that label returning -NLE_NOMEM. And nl80211 addresses interfaces by index, so if_nametoindex sits at the top of the ones that take a name.

Bringing an interface up is a different family

nl80211 creates the interface. It does not set IFF_UP, because that belongs to rtnetlink, so the two ip link set calls became one helper over libnl-route:

// Recuperation du lien actuel
    struct rtnl_link *link;
    ret = rtnl_link_get_kernel(sk, 0, ifname, &link);
    if (ret < 0) {
        fprintf(stderr, "rtnl_link_set_up: cannot get link %s (err %d)\n", ifname, ret);
        nl_socket_free(sk);
        return ret;
    }

    // Creation d'une copie pour appliquer les modifications
    struct rtnl_link *new_link = rtnl_link_alloc();
    if (!new_link) {
        rtnl_link_put(link);
        nl_socket_free(sk);
        return -NLE_NOMEM;
    }

    // Copie des proprietes existantes
    rtnl_link_set_ifindex(new_link, rtnl_link_get_ifindex(link));
    unsigned int flags = rtnl_link_get_flags(link);
    if (up)
        flags |= IFF_UP;
    else
        flags &= ~IFF_UP;
    rtnl_link_set_flags(new_link, flags);

    // Passage du lien original (non modifie) et du nouveau lien modifie
    ret = rtnl_link_change(sk, link, new_link, 0);

libnl wants the original object and the modified one so it can work out the difference itself, which is why the code copies the ifindex and the flags into a fresh rtnl_link before flipping the bit.

Channels became frequencies

The set path in nl80211 has no notion of a channel number. It takes NL80211_ATTR_WIPHY_FREQ in MHz, so the FIFO of channels became a FIFO of frequencies and one small function appeared:

static uint32_t channel_to_freq(unsigned int channel)
{
    if (channel >= 1 && channel <= 14)
        return 2407 + channel * 5;   // bande 2.4 GHz
    else if (channel >= 36 && channel <= 165)
        return 5000 + channel * 5;   // bande 5 GHz
    else
        return 0; // invalide
}

The 5 GHz line looks wrong for a second. It is not: channel 36 is 5180 MHz, and 5000 plus 36 times 5 is exactly that.

The hopping thread kept its shape and lost the fork:

void *channel_handler_run(__attribute__((unused)) void *v)
{
    uint32_t current_freq = START_FREQ;
    while (!quit) {
        current_freq = get_next_freq(&fifo);
        usleep(channel_switch_delay);
        if (nl_session_ptr)
            nl80211_set_freq(nl_session_ptr, monitor_iface, current_freq,
                             NL80211_CHAN_WIDTH_20_NOHT);
    }
    return NULL;
}

What the rewrite is worth

I did not benchmark it, so there is no before and after number here. What changed is structural. The steady state no longer creates a process every four seconds. The module no longer needs iw and ip installed to run. A failure comes back as a libnl error code printed next to the call that produced it, instead of an exit status from a child process.

The geteuid() != 0 check that used to sit in monitor_setup went away with the exec calls. The netlink send fails on its own now and prints its own error. I think that is the better trade, but it is harder to read when it happens over SSH on a machine you have not configured.

Two things are still open in that file. main_cleanup ends with //TODO (OPTIONNEL) liberer les interfaces wifi aussi, and the doc comment on the interface listing still carries \todo Séparer la sortie par interface physique, which starts to matter as soon as a probe has more than one radio. The header is also still declaring set_freq and next_channel, and neither has a definition anywhere in the tree any more.

Building just this module

The radiotap library the parser links against is packaged in Kali and, as far as I could find, nowhere convenient, so the README tells you to clone it and run cmake yourself. wifi/flake.nix builds this module on its own: it fetches radiotap-library into a derivation, writes a lili.h holding the handful of macros the module expects, and compiles three translation units against libnl, mosquitto, libpcap and cjson. It is still untracked in the repository, so treat it as scratch work rather than something the project has adopted.

Further reading

• The kernel's nl80211 documentation: what each command expects and which attributes are required.
• include/uapi/linux/nl80211.h: the enums and attribute names.
• libnl core documentation: sockets, callbacks and the error codes.
• libnl-route documentation: the rtnetlink objects used to change link flags.

Where this fits: Wireless detection over nl80211 in the portfolio.

Third year had an embedded systems project: design and build a device, PCB included. We built one half of a split ergonomic keyboard. Thirty keys, per-key RGB, a board we routed ourselves. Somewhere between the soldering sessions and the first working animation, the backlight took out the microcontroller.

What follows is what I would keep in that design, what I would not, and the calculation that should have happened before we ordered the parts. The code is coursework and stays private; the wiki page linked at the end is the public record of it.

What is on the board

The KiCad project carries 112 footprints on two copper layers. Two layers was a constraint we set at the start, one for the switch matrix and one for the LEDs, and it turned out to be routable.

Why the backlight is not on the MCU

Sixteen RGB LEDs is forty-eight PWM channels. Generating those in software on a 16 MHz AVR while also scanning a matrix and running a USB stack would have taken the whole semester. The TLC5947 does it on its own: 12-bit PWM generated internally at roughly 30 kHz, and the MCU only has to shift in a frame.

Two drivers are cascaded so one frame covers both. The MCU sends forty-eight channels of twelve bits, most significant bit first, starting from the last channel of the far chip, then pulses the latch line. From tlc5947.c:

for (int8_t c = NUM_CHANNELS - 1; c >= 0; c--) {
    uint16_t value = pwm_buffer[c];
    for (int8_t b = 11; b >= 0; b--) {
        if (value & (1 << b)) PORTB |= (1 << PB5);
        else                  PORTB &= ~(1 << PB5);
        PORTD |= (1 << PD0);   // SCLK high
        PORTD &= ~(1 << PD0);  // SCLK low
    }
}
PORTD |= (1 << PD6);   // XLAT
PORTD &= ~(1 << PD6);

That is the whole driver: 576 bits and a latch pulse, with no timer and no interrupt involved. The frame is about 72 bytes, and at the rate the animation refreshed it cost nothing I could measure. This is the decision I would keep exactly as it is.

The backlight current, and the resistor that decided it

A TLC5947 is a constant-current sink. One external resistor per chip sets the current for all twenty-four of its channels, and the datasheet relation is this:

IOUT = (VRIREF / REXT) * 31.25        VRIREF = 1.2 V typical

REXT = 1.97 kOhm  ->  ~19 mA per channel  ->  48 channels  ~ 0.9 A
REXT = 3.3  kOhm  ->  ~11 mA per channel  ->  48 channels  ~ 0.55 A

what we designed the supply around: ~300 mA at 5 V for the whole board

We fitted 1.97 kΩ on both IREF lines. For a single LED, 19 mA is reasonable. For forty-eight channels at once it is about 0.9 A, against a supply sized for roughly 300 mA for everything. During testing, with the brightness turned up, the ATmega32U4 died. It took us a while to accept that the chip itself was gone, and the confirmation was desoldering it and fitting a new one.

The fix was two resistors. 3.3 kΩ puts each channel near 11 mA, and nothing heats up any more. The firmware then deals with the colour imbalance, because the APFA3010 datasheet shows red being weaker than green and blue at the same current:

// according to the datasheet, reds are much weaker than blues and greens
tlc_set_led(i, r >> 1, g >> 4, b >> 4);

The margin is still thin, and it is worth writing down. At 11 mA per channel, sixteen LEDs at full white is around half an amp, which is still above the 300 mA we designed for. The board gets away with it because the animation never drives every channel to full. That is a workaround. A second version needs the resistor chosen from the power budget first, and for a 5 mA target that is about 7.5 kΩ.

The matrix, and the two microseconds

Five rows and six columns is eleven pins instead of thirty. They are spread across four ports, which looks untidy in the source but was a routing decision: columns on PORTF, rows on PORTC, PORTB and PORTD, chosen so the traces could actually leave the MCU on two layers. Four of those PORTF pins are JTAG pins, so the init disables the JTAG interface to get them back.

Debounce is a shift register per key. Eight equal samples in a row change the state, and anything in between leaves it alone:

debounce_state[r][c] = (debounce_state[r][c] << 1) | (raw_state ? 1 : 0);

if (debounce_state[r][c] == 0xFF && !matrix_state[r][c]) matrix_state[r][c] = true;
else if (debounce_state[r][c] == 0x00 && matrix_state[r][c]) matrix_state[r][c] = false;

There is one line in the scan loop I have not fully explained, and I would rather write it down than tidy it away:

select_row(r);

// Keyboard doesn't doesn't work without this for some god forsaken reason
// hypothesis: wait a tiny bit for the voltage to drop (capacitance on the lines)
_delay_us(2);

Without that delay the scan reads keys nobody pressed. My explanation is the one in the comment: the row has to actually fall, and with thirty diodes and long traces on both sides there is enough capacitance for the column to be read too early. I have never measured it. The delay costs nothing, so it stays.

The rainbow knows where each key is

The animation sweeps hue. The usual way to do it numbers the LEDs left to right, which means the gradient follows the channel index. The channel order on the drivers has nothing to do with where the LEDs sit on the board, so that version looks scrambled once it is built.

I took the x and y coordinates of all sixteen LEDs out of the KiCad placement and put them in main.c. Each LED's hue is the global hue plus a weighted offset from its position:

float hue = global_hue
            + alpha * (led_positions[i].x - x_ref)   // alpha = 0.5
            + beta  * (led_positions[i].y - y_ref);  // beta  = 0.3

Adding an LED then means adding one coordinate pair instead of re-deriving an order. It is the part of the firmware I like most.

Soldered on the wrong face

The switches went onto the opposite side of the board from the one the layout assumed. Reworking thirty sockets was one option. Mirroring the keymap table in firmware was the other, and we took that one, with an apology left in the source:

// KEYBOARD DEFINITION HERE.
// IT'S MIRRORRED BECAUSE WE MESSED UP THE FACE ON WHICH WE PUT THE BUTTONS
// SORRY.

The table maps the matrix to the left half of an AZERTY layout, escape and the number row along the top, modifiers down the thumb column. One entry is not a key code but a sentinel that the report builder turns into the left-control modifier byte, so that key behaves as a modifier. The report itself is the standard HID boot keyboard report, which caps it at six simultaneous keys plus modifiers.

The link to the other half

The two halves talk over a 3.5 mm jack using the MCU's second UART at 115200 baud. A packet is a start byte, a command, a length, the payload, and a checksum that is a plain sum modulo 256. The thirty bits of key state pack into four bytes, so a full matrix update is nine bytes on the wire.

0xAA | cmd | len | data[len] | checksum        cmd 0x01 = matrix, len = 4

The transmit side runs every fifty loop iterations. The receive side is a byte-at-a-time parser with a length guard, and it checks the checksum before accepting anything. The step that never happened is the merge: the received matrix is not folded into what goes out over USB, and that place in the source is a literal //TODO. The other half was built by another group, and we never got the two boards working together on a desk. So this project is one working half with a link that is implemented on both ends and unused.

We may build a tidier second version some day. Reading this repo already says what would change: choose the IREF resistor from the power budget, keep the drivers and the hot-swap sockets, and finish the merge before wiring up a second board.

Further reading

• The project wiki page: the full hardware write-up in French, including the power section and the dated build log.
• TLC5947 datasheet: the 24-channel driver, the IREF relation, and the frame format.
• LUFA: the AVR USB stack the HID layer sits on.

Where this fits: A split mechanical keyboard, designed and built in the portfolio.

Everything I run runs on hardware I can point at: my laptop, the retired laptop I keep for conservation, and a headless machine I call aleph. I had never operated inside a cloud account, and that gap bothered me, because most of what I read about security and infrastructure assumes the reader knows what an account looks like from the inside. So in September 2025 I opened one, put a single EC2 instance on the free tier, and spent time moving through it.

This is written about a year later, so it is a description of how the platform behaves rather than a log of what I typed. The parts worth keeping are the ones that changed how I think about the machines I already run, and those are what this note is about.

The free study guide as a map

I began with the CLF-C02 exam guide, which is a free PDF and the closest thing AWS publishes to a table of contents for the platform. It divides the content into four domains: Cloud Concepts at 24 percent, then Security and Compliance, Cloud Technology, and Cloud Financial Management. As a map it is excellent. As teaching it is weak, because almost every line is a noun phrase. Region, availability zone, edge location, security group, key pair, AMI, instance profile, launch template.

Reading those words was easy and almost none of them stayed, because they named operations I already performed under other names. So I launched an instance, to have one thing the nouns could point at.

The account, and the free tier

The free tier moved just before I got there. The EC2 free tier usage page draws the line at 15 July 2025. An account opened before that date gets 750 hours a month of t2.micro or t3.micro for the first twelve months. An account opened after it gets credits instead, $100 at signup with up to $100 more for working through the foundational services, and a six month Free Plan, with no EC2 hour allowance in it. I opened mine in September 2025, so it is on the second model, and the difference is one you feel once you are inside: a quota tells you what is free, credits tell you how much of the normal price you have left.

One instance in eu-west-3, the Paris region, on an Ubuntu image, at a free tier size. I did most of the moving around from the command line, because aws ec2 describe-instances was faster than finding the right page in the console.

The security group sits outside the machine

This is where the platform and my habits diverged most, and it is the part I found most interesting. On my own machines the firewall runs on the box. I can list the rules, change them over ssh, and if I get it wrong there is still a local console to fix it from. A security group is attached to the network interface instead of to the operating system, and a packet that matches no inbound rule is dropped before the instance ever sees it. It is stateful, so one inbound rule is enough for the reply traffic to come back; there is no outbound rule to write for a response.

The consequence is a debugging distinction I did not have before:

• Connection refused means the packet reached the machine and no process was listening on that port. The security group did its job and the machine answered.
• A hang that ends in a timeout means the group dropped the packet. Nothing on the instance is involved, so nothing in its logs will tell you why.

The other difference is what happens when you lock yourself out of SSH. There is no console behind an EC2 instance. That gap is what AWS Systems Manager Session Manager is for: it opens a shell through the EC2 API using an instance role, so the recovery path is a second API rather than a keyboard plugged into the machine. I would rather have a console I can reach with a cable, and I would still put the instance behind a tailnet the way I put aleph behind one, but the API recovery path is a reasonable answer to a problem my own machines do not have.

The key pair, and what the image decides

The console generates the private key and hands it to you once. There is no way to read it back later, only to swap the key pair on a stopped instance and reboot. The username you log in as is decided by the image rather than by you: ec2-user on Amazon Linux, ubuntu on the Ubuntu images, and something else again on the rest. Mine was an Ubuntu image, so the user was ubuntu, and that was the one point in the whole exercise where the cloud and my own machines looked like the same job.

When the instance went away I deleted the key with it. A private key for a machine that no longer exists is just a file waiting to be found, and the platform has no way to hand one back, which is the right design even though it makes the whole setup impossible to resurrect.

A web server, and then IAM

I put nginx on it, listening on port 80 with the security group open to the whole internet, and served a site of mine from it rather than the default page. That was the part I kept turning over: an address in Paris that a browser anywhere could reach, on a machine whose entire existence was a handful of API calls. It also moved the audit question somewhere I was not used to looking. The part that decides what reaches the listener is not on the machine, so ss -tlnp and a ruleset dump are only half the answer.

IAM is the part of the account the guide weights most and the part that has no clean equivalent in anything I run at home. The idea worth taking away is the difference between a user with a long lived access key and a role attached to an instance. A role hands the instance temporary credentials through the metadata service, so there is no secret to write into a file on a machine that is not yours, and nothing to rotate when the machine is replaced.

The failure mode the Security and Compliance domain keeps circling is an identity with more room than the job needs, attached to something nobody is thinking about any more. On a platform where one policy reaches across every resource in the account, that is easy to arrive at by accident. My own habit is least privilege on a single box, and I would write the policy before the instance next time.

Stop, then terminate

A stopped instance is not billed for instance hours, but the EBS volume attached to it is billed for as long as it exists, and so is a public IPv4 address. Since 1 February 2024 AWS charges $0.005 per hour for every public IPv4 address, attached to something or not, with 750 hours a month of it included in the older free tier. The instance lifecycle page says it in one sentence: some resources, EBS volumes and Elastic IP addresses among them, incur charges regardless of the instance state.

So stop-instances is the command that looks like turning a machine off and is not, and terminate-instances is the one that releases the address and by default deletes the root volume. I stopped it, then terminated it, which is the order that actually leaves nothing behind. On the model my account is on, those charges come out of the credits rather than out of a quota, so they are easy to miss: nothing arrives as money, and the volume and the address are still there.

CloudTrail, which I do not have at home

One thing in the account is genuinely ahead of what I run at home, and it is the thing I went back and thought about most: every action in an AWS account is an API call, and CloudTrail records API calls. So the account has a history of decisions by default, not a history of file contents.

On aleph and on my laptop, a change committed to the flake leaves the file and its git history, which is good provenance for configuration. A change made by hand in a shell leaves nothing behind but shell history, and a change made by a compromised process leaves less than that. An audit log of who called what, with an identity attached to each call, is a thing my machines do not have and should.

My machines and the cloud, side by side

The instance did most of the teaching, because it turned each noun in the guide into something I had touched. The mapping onto what I run at home is not exact, but it is close enough to be useful.

Further reading

• AWS Certified Cloud Practitioner exam guide (CLF-C02): the four domains and what each one expects you to know.
• AWS Free Tier FAQs: the July 2025 change from the twelve month model to credits.
• Amazon EC2 instance state changes: which states are billed, and which resources are billed anyway.
• The public IPv4 address charge: the announcement, the rate, and the free tier exception.