DEV Community: Jules

Typing While the Agent Thinks

Jules — Fri, 31 Jul 2026 18:18:13 +0000

I asked Claude Code to refactor a module and then I sat there.

Not for long. Long enough to open a browser tab, read half a thread about something I did not care about, and lose the thing I had been holding in my head. When the run finished I had to read my own prompt again to remember what I had asked for.

That happens many times a day now. I never measured it properly and I am not going to pretend I did, but the shape is obvious: a run is rarely under a minute, it is sometimes five, and the gap is exactly the wrong length. Too long to stare at. Too short to start anything.

So I went looking for something to put in the hole, and everything I tried was wrong in the same way. A typing trainer feeds you scrambled words and you get faster at hitting keys. That is it. You spend twenty minutes a day at it and the only thing that improves is the muscle. Meanwhile the actual bottleneck in my day is not how fast my fingers move. It is how long it takes me to write a clear pull request description, a ticket, a paragraph like this one.

The best two minutes to practise writing are the two you spend waiting for a machine to finish writing.

The constraint

It has to be over the moment the agent is. That is the whole design problem in one sentence.

Everything falls out of it. No login, because a login costs more than the gap. No network, because a spinner in a two minute window is the same as a failure. No session you have to finish, because the thing you were actually doing comes back at an unpredictable moment and you need to be able to walk away mid sentence with nothing lost. And the unit of work has to be one sentence, not one paragraph, because one sentence is what fits.

One sentence turns out to be enough to teach something, as long as you pick the sentence on purpose.

What it does

It is called wordwright. You type a sentence, it measures you, and then it tells you why the sentence is built the way it is.

  wordwright                                        intermediate  ·  drill 3/8
  ────────────────────────────────────────────────────────────────────────────

  ▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░   58 wpm   97% accurate   3.0s

  The deploy finished at two; nobody noticed until the morning.

  semicolon · clause-joining

  esc quit    ctrl+r restart    tab skip

That semicolon is the point of the exercise. You type the sentence, you see your speed, and then you get two or three sentences on why a semicolon can join those two halves and a comma cannot. Every sentence in the corpus is there to carry one pattern: an appositive that defines a noun in passing, a dangling modifier, the difference between fewer and less.

Wrong characters stay on the screen in red rather than being rejected. A trainer that refuses the wrong key teaches you to hammer a key until it gives, and it quietly hides the mistake from the report. Here the miss lands, you can see it, and you decide whether to go back for it. Correcting it still costs you accuracy, because it happened.

Then there is the other mode, which is the one I actually built the tool for. It gives you a brief and you write the sentence yourself.

  score      ▓▓▓▓▓▓▓▓▓▓▓░░░░░  2/3 checks

  yours      the outage was caused by an expired certificate

  checks     ✗ Still passive. Put the actor in front of the verb: something
               did something.
             ✓ 12 words or fewer
             ✓ used "certificate"

  mechanics  Open with a capital letter.

  one way    An expired certificate caused the outage.

There is no model in the loop. Not one call, not one token. Each check is a rule sitting in a JSON file that you can open and read: this pattern must appear, this one must not, stay under twelve words, use this word. That is a long way short of a human editor and it buys three things I was not willing to give up. The verdict arrives in the same frame as the keypress. It is identical every time, so a rule you failed yesterday fails the same way today. And it works on a train.

Grading is split in two on purpose. Mechanics are the rules that hold for anything you write, so a capital at the front and a stop at the end. The checks are the actual lesson, and each one fails with a hint that tells you what to do rather than what you did. "Still passive, put the actor in front of the verb" is useful. "Incorrect" is not.

Getting it

npm install -g wordwright
wordwright

Node 20.11 or newer, no runtime dependencies, nothing to configure. If you would rather not install anything, npx wordwright runs it once and leaves nothing behind.

wordwright                     pick a level and a mode, then practise
wordwright drill               type sentences, measured in words per minute
wordwright compose             write to a brief, graded on grammar and intent
wordwright stats               speed, accuracy, streak, and your weakest patterns
wordwright packs               every pack loaded, and anything that failed to load
wordwright add my-pack.json    install a pack of your own

Bare wordwright asks you for a level and a mode and then runs eight exercises, which lands somewhere around two minutes. --count 3 makes it shorter. --level advanced skips the first menu. Escape leaves at any point and keeps everything you finished.

There are three levels. Beginner is the ground you stand on, so its and it's, subject and verb agreement, the comma before and. Intermediate is the joins: semicolons, comma splices, active voice, parallel structure. Advanced is rhythm and precision, which means appositives, the short sentence that lands after a long one, cutting the hedges, and the words that compress a whole clause into one.

Your history is a single file at ~/.wordwright/progress.json. Every number the tool shows is derived from it when you ask, so nothing goes stale, and nothing is sent anywhere because there is nowhere to send it to.

What it picks next

A trainer that serves random sentences trains what you are already good at.

Every exercise carries focus tags, 84 of them across the corpus, so semicolon, active-voice, its-vs-its, rhythm. Each attempt you finish scores the tags it touched, weighted so a recent attempt counts for more than an old one, and the next session leans towards the tags you are worst at and the exercises you have not seen in a while.

Two guards stop it becoming a punishment loop. An exercise you did in the last hour gets pushed down hard, and a little jitter goes into every priority, so your three worst sentences do not come back on a loop until you resent them. Practice, not detention.

How the interface is put together

This is where the interesting part is, and it is not the terminal drawing.

The shape is one rule: exactly one file is allowed to know that a terminal exists. Everything else is a pure function.

flowchart LR
  subgraph impure["app.ts, the only impure file"]
    T["Terminal: raw mode, alternate screen, the clock"]
  end
  subgraph pure["pure, and therefore testable"]
    K["keys.ts: bytes to key presses"]
    E["engine: typing, grading, selection"]
    R["render.ts: state to an array of lines"]
  end
  T -->|"stdin chunk"| K
  K -->|"key"| E
  E -->|"state"| R
  R -->|"lines"| T
  E -->|"attempt"| P[("~/.wordwright/progress.json")]

The typing engine holds an immutable state and never reads the clock. The current time comes in as an argument to every function that needs it, which is the only reason the timing tests are not flaky. A test hands it three keystrokes and a fake stopwatch and asserts on the words per minute, with no waiting and no tolerance window.

The key parser takes a string and returns key presses, and it exists because typing fast is messier than it looks. Several characters arrive in a single chunk when your hands are moving. An arrow key arrives as three bytes and must not be read as somebody typing a bracket. Because it is pure, a test can drive an entire session by feeding it a string, with no terminal attached anywhere.

The renderers take state and return an array of lines. They do not write to standard output, they do not read the clock, and they know the width of your window only as a number somebody passed them. So the tests assert on what you would see, which for a typing trainer is most of what is worth asserting on. Every colour goes through one paint function that takes a plain flag, so every screen has a colourless twin. That is what --plain gives you, and it is also what the tests read.

Two details in the impure file earned their place.

The first is that a frame is drawn by moving the cursor home and repainting, erasing each line as it goes and then erasing whatever is left below it. The obvious version clears the screen and then writes, and the obvious version flickers, because for one frame there is genuinely nothing there. Nobody notices this until they type fast.

The second is that the restore is registered before the screen is entered, not after. Raw mode and the alternate screen are things you borrow from somebody's terminal. If the process falls over between borrowing and giving back, they are left with a terminal that does not echo what they type, and their only move is to close the tab. So the handlers for exit, interrupt and terminate go on first, they all run the same restore, and the restore is guarded so that calling it twice is harmless.

There is one timer in the whole thing. It repaints every 120 milliseconds while a drill is running, and it is there for one reason: the elapsed seconds have to keep moving when your hands are not. Keystrokes paint their own frame.

The result is 3,476 lines of TypeScript, of which 1,134 are tests. There are 127 of them, on Node's own test runner, with no framework and no dependencies, and they run in about 130 milliseconds. One of those tests is worth stealing for any project that ships content: every model answer in every shipped pack has to pass its own checks. An exercise whose own answer would be marked wrong is a bug, and it gets caught long before it reaches you.

The one that bit me

The repository runs straight off TypeScript with no build step, because Node strips the types for you now. That is a genuinely nice way to work, and it stops working the moment somebody installs your package: Node refuses to strip types for anything under node_modules. The first version I packed would have failed on every machine that installed it.

So the build compiles to JavaScript, and continuous integration installs the packed tarball on Node 20, 22 and 24, on Linux and macOS, and runs the command for real before anything is published. Type checking proves the code compiles. Only installing it the way a stranger would proves that it runs.

What it does not do

It does not know whether your sentence is good. It knows whether it is passive, whether it used the word, whether it stayed under twelve words, and whether the mechanics hold. It will not teach you to type if you have never touched a keyboard, so learn the home row somewhere else and come back.

And the corpus is 81 exercises. That is weeks of daily practice and it is nowhere near enough forever, which is exactly why the pack format is the first thing documented in the README. A pack is a JSON file you drop in ~/.wordwright/packs/, wordwright template prints the skeleton, and wordwright add validates one before it goes in. If you write a pack for the mistakes you actually repeat, I would like to see it.

The code is at github.com/juliantellez/wordwright, it is MIT, and it is on npm.

Now go and give your agent something slow to do.

This was originally published on juliantellez.com. It is part of my newsletter on video, streaming, and building reliable systems from scratch: the architecture, the tradeoffs, and the occasional 3am incident.

If it was useful, subscribe for the next one. No spam, unsubscribe anytime. If you are building something similar and want to compare notes, say hello. I read every message.

Built from scratch, like everything here.

Who needs a VPN anyway?

Jules — Wed, 29 Jul 2026 13:03:34 +0000

As previously discussed; the internet is a collection of interconnected computers, commonly referred as nodes. When your computer requests data the sender must dispatch it (over the wire) through many intermediate nodes until it reaches you. This strategy for dispatching data is commonly referred to as the store and forward model. But how do all these intermediate nodes know where to redirect the data so it gets to you? Well, there are a few rules to this game.

A,B,C,D represent middlemen nodes. From Wikipedia

There is a limit to how big the sent data can be, this is because there's an actual physical limit which is why an optimal size has been established. To overcome this limitation, data is split into smaller packets. Each packet or IP Packet contains a source and a destination address. Sounds familiar? This is how a postal service may implement their dispatching model.

Photo by sue hughes on Unsplash

The relay between sender to receiver may involve several intermediate nodes, where each node will inspect the packet and forward it closer to its final destination. When the requested data finally arrives to you it has been inspected by many different nodes.

But why should we care about middlemen glancing over our data? As we mentioned in our previous article; The internet isn't trusted because of its architecture, but because of its users. Allowing third parties to inspect even just the route of your data can have several ripple effects:

Gain commercial advantage. If a third party or ISP is affiliated to a certain vendor and you purchase from its competitor, said party may slow down ('throttle') or even block access to it. Since your overall experience with the vendor was poor, next time you purchase the same or similar item you will consider its competitor.
Build a commercial profile. By analysing your data, a third party may build a profile of your preferences, correlate them with your local peers and sell the findings to a vendor. Ever wondered why everybody gets the same kind of adverts in the same area?
Censoring Information. A third party could have an affinity for a certain topic and could therefore block access to the opposition.

Small misdirections such as throttling would ultimately change your behaviour.

I will leave you with this reflection: 20% of the causes are responsible for 80% of the effects. The law of the vital few or Pareto Principle can be traced down to human behaviour in the form of habits. Allowing others to determine how you interact with the world will ultimately change you, only you won't be able to notice.

There are other reasons to use a VPN, such as privacy (not secrecy) and net-neutrality. I will be writing about them as they all deserve attention, until then. 👋

Originally published on Medium.

If it was useful, subscribe for the next one. No spam, unsubscribe anytime. If you are building something similar and want to compare notes, say hello. I read every message.

Built from scratch, like everything here.

What is a VPN?

Jules — Wed, 29 Jul 2026 13:02:58 +0000

Photo by Jakob Søby on Unsplash

VPN stands for Virtual Private Network. From a very high level, a network is simply a group of computers (commonly referred as nodes) that share resources, such as pictures, media, data, etc. These networks are said to be private when no external nodes have access to its resources.

You can create a small network at home by connecting two computers to each other with say, an ethernet cable. In fact, you can connect as many nodes as you like; you will need a network switch and a lot of patience. It's quiet fun! provided you don't mind thousands of cables lying around the house.

From Pinterest

As you can imagine, having every node hard-wired to its peers alone just doesn't scale. What happens when you run out of room? what if you would like to connect thousands, millions or even billions of nodes? How about making their resources accessible in different locations? To overcome this problem, nodes connect to an specialised node called a router, thanks William 'Bill' Yeager! 🚀

Since routers are nodes themselves, they can connect smaller networks; allowing the parent network to scale infinitely. Sounds familiar? This is a very simplified version of how the internet works.

From developer.mozilla.org

When your computer connects to the internet, it becomes accessible on the network. In order to retrieve and send information on the web, it has to go through many routers and the information flowing back and forth isn't guaranteed to be private. The internet is an untrusted network, of course safety measures have been placed, such as SSL; However the internet isn't trusted because of its network architecture, but because of its users.

So we know that for networks to be private, no external nodes should have access to its resources. But what about the word virtual? what are we referring to? Well, a virtual network is a sub network of geographically unrelated nodes; connected through the parent network, such as the internet. It simply means that these nodes aren't connected physically.

We now know what it means to be Virtual, to be Private and what a Network is.

From giphy.com

Links

Originally published on Medium.

If it was useful, subscribe for the next one. No spam, unsubscribe anytime. If you are building something similar and want to compare notes, say hello. I read every message.

Built from scratch, like everything here.

Handling complexity in lambda functions

Jules — Wed, 29 Jul 2026 13:02:22 +0000

Photo by NASA on Unsplash

TLDR;

Middlewares can handle the complexity of your lambdas while isolating business logic and cross-cutting concerns in reusable components that can be modelled by event cycles.

I have had the luck and pleasure of working with lambda functions recently and boy I am having fun! The idea of having an event-driven execution environment is both daring and exciting. If you are new to the FaaS world, don't worry, the community has already prepared a curated list of reads for you here and here. Have a browse, drink some coffee. ☕

As you can see, (because you checked at least one of the links, didn't you?) A huge weight has been lifted. We can now develop, run and manage applications without the intricacy of building and maintaining infrastructure. But with new beginnings, new challenges arise. One of such problems and the reason for this blog is function complexity.

How complex is too complex?

Generally speaking, when writing lambda functions you would organise them into a series of dedicated modules following the single responsibility principle. If you would rather do otherwise, please read this excellent blog comparing monolithic vs single purposed functions. Isolating application from business logic reduces code complexity, simplifies reasoning and will help you debug your code more efficiently. Your colleagues and your future self will thank you.

Take for example some sort of CRUD API, we would like to make sure that a payload is properly formatted before handling any data. The payload validation could emit an error that would communicate its status to the consumer. If the validation was successful it would then move onto executing some business logic. For both scenarios, we would also want to set up some percentile tracing and error logging. While all of these sound great, we have essentially mapped out a request lifecycle with various cross-cutting concerns:

Data validation.
Error detection and correction.
Logging.
Monitoring.

I know what you are thinking… (gif from giphy)

Following the serverless mantra, we should outsource anything that isn't related to the core business, so wouldn't it be great if we could just focus on the business logic and outsource these application-specific problems too? Of course, this isn't a new concept and we have been using it in web frameworks like hapijs and express for quite some time now.

Lambda Middleware

A lambda middleware is essentially a function that contributes to managing cross-cutting concerns in a consistent manner. It provides a clear separation of application and business logic and outlines an easy to reason configuration cycle. It is the glue that when adopted by everyone in a team becomes the lingua franca that supports and creates features. But do we really need a middleware? Well, look at the current state of your lambdas and ask yourself a few questions:

What does the code look like?
Can you envision anyone supporting it in at least 2 years?
How much business logic expertise do you need? (if specialised then separation is imperative)
Is logic intertwined and hard to reason about?
Does the project have a clear path or do you see it going in different directions?
How will the project look like the day the expert leaves?
Are best-practices enforced and maintained?

Jack Nicholson approves. (gif from giphy)

Enter Lambcycle

Lambcycle 🐑 🛵 is a declarative middleware for lambda functions. It defines a configurable event cycle and allows you to focus on your application's logic. It has a "Feature as Plugin" approach, so you can easily create your own plugins or reuse your favourite packages with very little effort.

In practice there is no such thing as an un-opinionated framework, every idea is an opinion and a way of working with your application. Lambcycle favours configuration over code and believes that business logic should be as isolated as possible.

Labmcycle flow chart.

Lambcycle enhances lambda functions with a few extension points (see graph), each of which can be used to interact with the event in a decomposed manner.

The first extension point is Request which occurs immediately after the lambda is called. You can use this step for parsing, validation, etc...

Note: If you are thinking of auth, please consider a lambda authoriser instead.

The Pre Handler extension comes in handy when you need to adapt data to fit an interface. It is also a great place for fetching secrets.
The Handler, where your beautiful business logic lives.
Next up is the Post Handler, use this extension to validate and/or cache the output of your business logic.
Error is an implicit extension for logging and tracing.
And finally Pre Response, your chance to format a response to the consumer (which could be data or an error).

Using the middleware

import Joi from 'joi'
import lambcycle from 'lambcycle'
import joiPlugin from 'lambcycle/dist/plugin-joi'
import bodyParser from 'lambcycle/dist/plugin-body-parser'
import realTimeEventTracker from './bugFreeBizLogic'

const businessLogic = async(event, context) => {
    const {error, data} = await realTimeEventTracker(event.data)

    if(error) {
        throw error
    }

    return data;
};

const schema = Joi.object().keys({
    assetId: Joi.string().required(),
    competition: Joi.string().required(),
    sport: Joi.string(),
    tournamentCalendar: Joi.date(),
}).required()

const handler = lambcycle(businessLogic)
.register([
    bodyParser({type: 'json'}),
    joiPlugin(schema)
])

export default handler

The example above leverages express' body parser and hapi's joi validation. We have configured both plugins with a parsing type and a validation schema respectively. By abstracting these two we have rid of complexity and shift the focus to the business logic. Note that a more robust lambda would include error tracing, and response plugins.

Crafting a Plugin

The possibilities are endless when it comes to plugins! Do you have something in mind? Contributions are more than welcome ❤️

import * as Sentry from '@sentry/node';
import MyAwesomeIntegration from './MyAwesomeIntegration'

const sentryPlugin = (config) => {
    Sentry.init({
        dsn: `https://${config.key}@sentry.io/${config.project}`,
        integrations: [new MyAwesomeIntegration()]
    });

    return {
        config,
        plugin: {
            onPreResponse: async (handlerWrapper, config) => {
                Sentry.captureMessage('some percentile log perhaps?')
            },
            onError: async (handlerWrapper, config) => {
                Sentry.captureException(handlerWrapper.error);
            }
        }
    }
}

export default sentryPlugin;

In your lambda ….

import lambcycle from 'lambcycle'
import sentryPlugin from './sentryPlugin'

const myApplicationLogic = async (event, context) => {
    return await someLogic()
}

const handler = lambcycle(myApplicationLogic)
.register([
    sentryPlugin({
        key: process.env.SENTRY_KEY,
        project: process.env.SENTRY_PROJECT,
    })
]);

export default handler;

DX

Lambcycle has been built with developer experience "DX" in mind and ships with type definitions, for consistency and auto-completion 🚀 (VScode only).

Lambcycle DX.

Conclusion

It is a brave new world and serverless is here to stay! Promoting reusable components and consistent error handling will help you and your team create and support features in a more controlled and organised fashion. Lambcycle's main goals are to shift the conversation around a predictable unidirectional cycle and encouraging component reusability across features. Its worth mentioning that for more complex scenarios you should be looking at Step functions. Let me know if you would like to know more about them in the comments, in the meantime check out these use cases!

Special thanks to the legendary burning monk for the in-depth review of this article.

Originally published in the DAZN Engineering publication on Medium.

If it was useful, subscribe for the next one. No spam, unsubscribe anytime. If you are building something similar and want to compare notes, say hello. I read every message.

Built from scratch, like everything here.

Talking to Claude Code through an Alexa

Jules — Wed, 29 Jul 2026 13:01:45 +0000

This was an afternoon experiment, so read it in that spirit. The goal was to start real coding work by talking to a speaker: not "set a timer", but "work on the board script", and have an agent plan it with me and go and do it. No laptop open.

I gave myself a few hours, which means there are shortcuts everywhere. The backend is literally my laptop. The public entry point is a free tunnel. There is exactly one user, me, and no accounts. None of that would survive contact with real users, and I will come back to what a grown-up version looks like at the end. But the core turned out to be more interesting than I expected, because the main constraint forced a better design than the obvious one.

The wall everything runs into

Alexa cuts off a skill's response after about eight seconds. That is the whole design problem in one sentence.

A coding agent does not fit in eight seconds. Even just asking Claude to think of a few options for a task takes anywhere from four to twenty-plus seconds. So you cannot do the obvious thing, which is take what the person said, ask Claude about it, and speak the answer. Alexa will have hung up long before Claude replies.

Once you accept that nothing useful finishes in the window, the design falls out of it: acknowledge instantly, think in the background, and surface the thinking somewhere the eight seconds do not apply.

A planning conversation, not a command

Here is what actually happens when I use it.

me:    "Alexa, open assistant"
claude: "Claude ready. What should I work on?"

me:    "work on the board script"
claude: "Okay, work on the board script. I'm putting a few options on the
         dashboard. Tell me which one or describe what you want, then say go."

me:    "the second one"
claude: "Here's the plan: add a --since flag to the board script. Say go to
         start, or add more."

me:    "go"
claude: "Starting now: add a --since flag to the board script. Watch the
         dashboard, and ask me for the result."

The moment I describe a task, the server does two things at once. It replies immediately with a short acknowledgement, well inside the window, and it spawns a detached job that asks Claude to turn my vague sentence into two or three concrete, short options. Those options land on a dashboard, and the next thing I say is resolved against them. "The second one", "option two", and "three" all map to a choice; anything else is folded in as more detail.

sequenceDiagram
  actor You
  participant Echo as "Echo / Alexa cloud"
  participant Mac as "alexa-claude (my Mac)"
  participant Claude
  You->>Echo: "work on the board script"
  Echo->>Mac: signed request
  Mac-->>Echo: ack in under a second
  Mac->>Claude: generate options (background)
  Claude-->>Mac: options appear on dashboard
  You->>Echo: "the second one" ... "go"
  Echo->>Mac: signed request
  Mac->>Claude: run task in a tmux session
  Mac-->>Echo: "starting, ask me for status"

So the latency that made the naive design impossible becomes invisible: by the time I have heard the acknowledgement and decided what I want, the options are already there. The prompt gets built up across a couple of turns, and "go" commits it.

(The skill is invoked as "assistant" rather than "claude", because Amazon will not let you claim a single well-known word as a custom invocation name. It just introduces itself as Claude.)

The jobs are real sessions

When I say "go", the task does not run as some opaque background process. It starts in its own tmux session, which means it shows up in the same sessions tool I use for every other Claude session on the machine, and I can attach and watch it work live:

sessions go <pid>   # drop into the running voice-started job

That mattered more than I expected. A voice command that spawns invisible work is unnerving. A voice command that spawns a session I can see, attach to, and read line by line is just a faster way to start something I already understand.

A dashboard that stays home

Voice is a poor channel for output, so the real surface is a small web dashboard the server renders. It polls every couple of seconds and shows the prompt being built right now with its options, the jobs with running, done, and failed badges, and a log of voice turns so I can see what it heard and what it said back.

The one decision I am quietly pleased with: the dashboard is refused on the public URL. The tunnel that lets Amazon reach my Mac would also let anyone who found it load my activity dashboard. But tunnelled requests carry an X-Forwarded-For header and direct localhost requests do not, so the server serves the dashboard only to local requests and returns a 403 to anything that arrived over the tunnel.

Hearing the answer

Long work reports back through whatever channel suits. The job streams to its log and its tmux pane the whole time. When I want the result out loud, I ask:

me:    "Alexa, ask assistant for the status"
claude: "Done, add a --since flag to the board script. <reads the tail of the
         output, kept short enough to be pleasant>"

If the machine has Telegram configured it also pushes the result to my phone, but that is optional sugar now rather than the main path. Short questions are the one thing answered inline: "ask assistant to tell me X" runs Claude read-only with a few seconds of grace, and speaks the answer if it finishes in time.

Keeping it safe enough

Even an afternoon toy that starts a coding agent from a public URL needs a lock, so every request has to prove itself. The server follows Amazon's verification for self-hosted endpoints: the certificate chain has to be a genuine Amazon address, the certificate has to be valid and issued for echo-api.amazon.com, the body has to verify against its signature, and the timestamp has to be recent so a captured request cannot be replayed. The skill id is a second lock on top. Questions run read-only; tasks run with a permission mode that edits files but still stops before risky commands.

What a real product would look like

Everything above is held together with the cheapest possible parts, and that is the right call for a few hours of play. But it is worth being honest about where the shortcuts are and what you would actually build instead.

The shortcuts: the backend is my Mac, so it only works while the machine is awake with the server and tunnel running. The entry point is a personal free tunnel, not a hosted endpoint. There is one user and no authentication, so "lock it to my skill id" is doing a lot of heavy lifting. And the agent runs directly on my real machine with access to my real files, which is fine for me and unthinkable for anyone else.

A product version inverts most of that:

flowchart LR
  Echo["Echo"] --> Alexa["Alexa cloud"]
  Alexa -->|"account linking (OAuth)"| GW["API Gateway"]
  GW --> Fn["Skill function: validate + enqueue"]
  Fn --> Q["Queue"]
  Fn --> DB[("Jobs / sessions store")]
  Q --> W["Sandboxed agent workers"]
  W --> DB
  W -->|result| Push["Proactive notifications / companion app"]
  Push --> Echo

The skill endpoint becomes a hosted, stateless function behind an API gateway, so there is no laptop to keep awake and no tunnel to babysit. Its only jobs are to verify the request, look up the user, and drop work on a queue, all comfortably inside the eight seconds. Account linking turns the single-user assumption into real multi-tenancy: each person links their own identity, and the skill id stops being the only thing standing between a stranger and a shell.

The actual agent work moves onto sandboxed workers, one isolated environment per user, so a task can never touch anyone else's files or the host. Job and conversation state lives in a small database rather than on one machine's disk, which is what lets a result reach you later, on a different device, after the voice session is long gone. And the results come back through Alexa's proactive notifications or a companion app, so "ask me for the status" becomes "your phone buzzes when it is done."

None of that is exotic. It is the boring, well-trodden shape of any async job system. The interesting part, the planning-conversation-around-latency, stays exactly the same. The afternoon version just runs it on a laptop instead of a fleet.

What it taught me

I went in thinking the hard part would be the voice. It was not; Amazon's speech to text is good and free. The hard part, and the fun part, was that the eight second wall made the naive design impossible and pushed me toward a better one: a system that never pretends to be fast, acknowledges instantly, thinks out of band, and gives you real attachable sessions and a live dashboard instead of a single hopeful reply.

It stopped being "an agent I sit in front of" and became "an agent I can start a conversation with from across the room, then go and watch it work." For an afternoon's wiring, that is a surprisingly nice way to begin a piece of work.

Built from scratch, like everything in this newsletter. Questions about the build? Say hello.

If it was useful, subscribe for the next one. No spam, unsubscribe anytime. If you are building something similar and want to compare notes, say hello. I read every message.

Built from scratch, like everything here.

Stop Letting AI Mark Its Own Homework

Jules — Wed, 29 Jul 2026 13:01:09 +0000

Last month I watched Claude Code write a beautiful authentication module. Clean abstractions, sensible error handling, well named functions. It looked like something a developer would write. Then I ran it. It failed immediately. The module was calling a method that didn't exist on the object it was importing. Claude hadn't made a logic error. It had made a confidence error. It wrote code that read correctly, explained correctly, and looked like it would work. But nobody had asked it to prove it. I stared at the screen for a minute, fixed the bug manually, and then thought: how many times will this happen again? Who is checking if all this code actually works?

The false confidence problem

Here's what I've noticed after a year of building with AI coding tools: the failure mode isn't that the code is bad. It's that the code is almost right. Close enough to pass a glance. Close enough that Claude will confidently explain why it works. Close enough that you could ship it, and if you don't have guards in place bugs will show up in production.

This isn't a Claude problem per se, it's an LLM problem. These models are trained to produce plausible output. And plausible code is the most dangerous kind of code, because it doesn't look wrong. The traditional answer to this has always been testing. Write the test first, write the implementation, run the test, see green. TDD isn't new. But here's what changed: the developer writing the code is now also an AI, and if the same AI writes the code and decides whether the code works, we've got a circular trust problem.

Reviewing your own code is basically marking your own homework. AI is no different.

The search for a solution

So I went looking for answers. The Claude Code ecosystem has some genuinely brilliant tools. GSD, short for Get Shit Done, stood out immediately. It interviews you about what you're building, creates atomic plans, and executes in phases using fresh subagents with clean context windows. It solves a great part of the context rot problem. If you haven't tried it, you should.

But after a few weeks, I kept hitting the same wall. GSD manages complexity and it's rather good at it. The planning is structured, the execution is disciplined, the main context stays clean. But when it comes to verification, the same agent that writes the code also checks the code. It basically asks "what must be TRUE for this to work?", which is a sensible question. But the agent is answering a question about its own output.

GSD was great at planning, but we also needed a trust boundary.

Building the boundary

The idea is simple: go back to basics and embrace TDD. What if the agent that writes the test is not allowed to write the implementation? That one constraint changes the flow. Once you enforce that separation, the agent can't fake confidence. The tester doesn't know how the code will work. The coder can't change the tests. And the thing that decides pass or fail isn't AI at all, it's your pytest, jest, go test. A mechanical process with no opinions and no ego.

I called it Greenlight. Green means done. Not "the agent thinks it's done." Actually done.

Introducing Greenlight

It has agents, each with hard boundaries. Here is the core team:

The Architect: defines what needs to be built, system design, constraints, scope.
The Tester: writes the (failing) tests based on the design. It can't see any implementation. It only knows what the code should do.
The Developer: receives the contracts and tests and writes code to fulfil the requirements. It is not done until both the requirements and tests pass. It can see the tests but cannot modify them.
The SecOps: reviews everything independently for vulnerabilities, injection risks, auth issues, and security antipatterns.

The test runner sits in the middle and judges. Not Claude. Not any AI. The machine. If tests pass, we move forward. If they don't, the coder keeps working. The project lives at github.com/atlantic-blue/greenlight.

Why Greenlight

Claude Code is powerful but permissive. It writes code, reviews its own work, and moves on. There's no external verification. Greenlight fixes this by enforcing agent isolation: one agent writes tests from contracts, another implements until tests pass, a third scans for vulnerabilities, and the test runner is the only judge. No agent ever sees its own tests.

This matters because:

AI reviews its own code poorly. Separating test writing from implementation prevents Claude from gaming its own tests.
TDD works better with AI. Contracts define WHAT, agents figure out HOW, and the test suite proves it works.
Security can't be an afterthought. Every slice gets a security scan. Every vulnerability becomes a failing test.

What Greenlight is

A set of Claude Code slash commands, agents, and engineering standards that enforce test-driven development:

10 agents with strict isolation boundaries (designer, architect, test writer, implementer, security, verifier, debugger, codebase mapper, assessor, wrapper)
16 slash commands (/gl:init, /gl:design, /gl:slice, /gl:ship, and so on) that orchestrate the workflow
Engineering standards (CLAUDE.md) covering error handling, naming, security, API design, testing, and more
Context degradation awareness, so agents stay under 50% context usage to maintain quality

What Greenlight is not

Not a framework, library, or runtime dependency. It installs config files and does nothing at build time.
Not a replacement for your test framework. It orchestrates Claude Code to use whatever test runner your project already has.
Not opinionated about language or stack. The contracts and standards are language agnostic.

Why is this interesting?

Claude Code just shipped Agent Teams, an experimental feature where multiple Claude sessions coordinate, message each other, and work in parallel. The agent roles already exist in Greenlight. The trust boundaries are already defined. What Agent Teams adds is concurrency and real-time coordination.

Right now, Greenlight's agents run sequentially. With Agent Teams, picture the test writer and implementer running as parallel teammates. The security agent scanning code as it's written, not after. The architect coordinating as team lead. Slices without dependencies executing simultaneously. All communicating through Claude Code's native messaging, all respecting their information boundaries.

The roles exist. The primitives exist. Wiring them together is the natural next step.

The real bottleneck isn't capability. The bottleneck is trust.

We're at a place in time where AI coding tools are good enough that capability isn't the limiting factor. Claude can write authentication modules, API gateways, database migrations, React components, infrastructure. The models will keep getting better. Costs will keep dropping. The bottleneck is trust.

Can you trust that what it wrote actually works? Can you deploy it without manually reading every line? Can you sleep at night knowing unreviewed code is running in production? TDD has always been the answer to that question. It just needed to be adapted for a world where the developer is also an AI.

Happy coding.

If you're building with Claude Code and want to stop vibe coding, give it a go. Or tell me I'm wrong. I'd genuinely love to hear how others are solving the trust problem. Greenlight is open source, MIT licensed: github.com/atlantic-blue/greenlight.

First published in my LinkedIn newsletter, Built from Scratch.

If it was useful, subscribe for the next one. No spam, unsubscribe anytime. If you are building something similar and want to compare notes, say hello. I read every message.

Built from scratch, like everything here.

Raspberry Pi Kubernetes Cluster: Start the Cluster (Issue #4)

Jules — Wed, 29 Jul 2026 13:00:33 +0000

Welcome to the Raspberry Pi Kubernetes home lab series. A bite sized informative guide to help you provision a cluster from scratch. By now we should have 3+ nodes running the latest version of Ubuntu and we should be able to SSH into them.

Today's issue will walk you through installing Kubernetes into your newly created cluster.

1. Requirements

At least 3 nodes with Ubuntu installed on them

The following 12 steps should be replicated on every node. We will set them up manually in this lab session, but will provide an automated way of setting up nodes via Ansible in a coming issue.

2. SSH into the node

ssh ubuntu@192.168.0.25

3. Set up hostnames and static IPs

Slave nodes need to provide a unique name to the master node upon registration.

# On each node
NODE_NAME=k8s-master # k8s-node-1 etc..
sudo hostnamectl set-hostname $NODE_NAME

4. Edit the hosts file so it maps IP addresses to hostnames

sudo nano /etc/hosts
192.168.0.25 k8s-master
192.168.0.26 k8s-node-1
192.168.0.24 k8s-node-2

5. Disable swap memory

Swap is space on the host disk that is used when the amount of physical RAM is full. Even though swap support has been added to Kubernetes, our Raspberry Pis have limited resources and we should account for such limitations.

sudo swapoff -a
sudo apt purge -y dphys-swapfile
# Test swap has been disabled
free -m

6. Edit the boot configuration

Append the following config to the boot file.

sudo nano /boot/firmware/cmdline.txt
ipv6.disable=1 cgroup_enable=cpuset cgroup_enable=memory cgroup_memory=1

7. Set up a container runtime (CRI)

Kubernetes has moved away from Docker. There are a few options out there (Docker included). We will be setting up containerd as our CRI.

sudo apt update -y && sudo apt dist-upgrade -y
sudo apt install -y containerd containernetworking-plugins

8. Create a config for containerd

sudo mkdir /etc/containerd
cat <<EOF | sudo tee /etc/containerd/config.toml
version = 2
[plugins]
  [plugins."io.containerd.grpc.v1.cri"]
    [plugins."io.containerd.grpc.v1.cri".containerd]
      [plugins."io.containerd.grpc.v1.cri".containerd.runtimes]

[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc]
          runtime_type = "io.containerd.runc.v2"
          [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options]
            SystemdCgroup = true
EOF

9. Forward IPv4 and set up IP tables

cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

sudo modprobe overlay
sudo modprobe br_netfilter

# sysctl params required by setup, params persist across reboots
cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF

# Apply sysctl params without reboot
sudo sysctl --system

10. Install kubeadm

Update the apt package index and install packages needed to use the Kubernetes apt repository:

sudo apt update
sudo apt install -y apt-transport-https ca-certificates curl

Download the Google Cloud public signing key:

sudo curl -fsSLo /usr/share/keyrings/kubernetes-archive-keyring.gpg https://packages.cloud.google.com/apt/doc/apt-key.gpg

Add the Kubernetes apt repository:

echo "deb [signed-by=/usr/share/keyrings/kubernetes-archive-keyring.gpg] https://apt.kubernetes.io/ kubernetes-xenial main" | sudo tee /etc/apt/sources.list.d/kubernetes.list

Update the apt package index, install kubelet, kubeadm and kubectl, and pin their version:

sudo apt-get update
sudo apt-get install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl

11. Install a Container Network Interface (CNI)

A CNI is required to implement the Kubernetes network model. We are going to install Flannel in this lab as it is compatible with MetalLB. Be sure to check out different networking models too, such as Calico.

wget https://github.com/flannel-io/flannel/releases/download/v0.19.2/flanneld-arm64
sudo chmod +x flanneld-arm64
sudo cp flanneld-arm64 /usr/local/bin/flanneld
sudo mkdir -p /var/lib/k8s/flannel/networks

We will install Flannel and apply its configuration once the master node is running.

12. Reboot (optional)

Reboot the nodes and start fresh. It will ensure that the boot file from step 6 is loaded in.

sudo reboot

Start the cluster

SSH into the master node and run:

sudo kubeadm config images pull
sudo kubeadm init --pod-network-cidr=10.244.0.0/16 --token-ttl=0

Save the token and discovery token provided by the initialisation. You can always generate a new token later by doing:

KUBE_TOKEN=$(kubeadm token generate)
kubeadm token create $KUBE_TOKEN --print-join-command --ttl=0

Create the kube config

mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

Node verification

kubectl get nodes
NAME       STATUS   ROLES  AGE VERSION
k8s-master NotReady master 55m v1.25.1

For the node to become ready we need to install our CNI from step 11.

Apply the CNI config

Assuming we are connected to our master node from the previous section, download Flannel's configuration:

wget https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml

Inspect the YAML configuration and replace the backend. More info is in the Flannel backend documentation.

sed -i 's/vxlan/host-gw/' kube-flannel.yml

Apply the config:

kubectl create -f kube-flannel.yml

Add slave nodes to the cluster

SSH into the slave nodes (k8s-node-1, k8s-node-2, ...) and run:

K8S_MASTER_IP=192.168.0.25
sudo kubeadm join $K8S_MASTER_IP:6443 \
--token <token here> \
--discovery-token-ca-cert-hash sha256:<hash value here>
# Output:
This node has joined the cluster:
* Certificate signing request was sent to apiserver and a response was received.
* The Kubelet was informed of the new secure connection details.
Run 'kubectl get nodes' on the control-plane to see this node join the cluster.

We are now ready to start inspecting and extending our cluster.

Leave a comment if you have any questions. We will be automating this setup next. Happy coding.

First published in my LinkedIn newsletter, Built from Scratch.

If it was useful, subscribe for the next one. No spam, unsubscribe anytime. If you are building something similar and want to compare notes, say hello. I read every message.

Built from scratch, like everything here.

Raspberry Pi Kubernetes Cluster: SSH into the Nodes (Issue #3)

Jules — Wed, 29 Jul 2026 12:59:56 +0000

Welcome to the Raspberry Pi Kubernetes home lab series. A bite sized informative guide to help you provision a cluster from scratch. By now you should have 3+ nodes running the latest version of Ubuntu. Refer to the previous guide if you would like to know more.

This issue walks you through communicating with your Raspberry Pi nodes through SSH.

Requirements

A Raspberry Pi node with the latest version of Ubuntu, connected to either your home router or an Ethernet switch
SSH should be enabled on the node

Install Nmap

brew install nmap

Nmap ("Network Mapper") is an open source tool for network exploration and security auditing, designed to rapidly scan networks.

Find the device's IP address

# Find the router's IP
netstat -nr | grep default

# Inspect nodes on your local network
nmap -sP 192.168.0.1/24

From the snippet above, the nodes are on 192.168.0.[24-26].

SSH into nodes manually

# ssh into device, password is usually "ubuntu"
ssh ubuntu@192.168.0.26

SSH into nodes with private keys

ssh-keygen -t rsa -b 4096

Add the SSH key to the node:

ssh-copy-id -i ~/.ssh/ansible ubuntu@192.168.0.26

SSH with the RSA key:

ssh -i ~/.ssh/ansible ubuntu@192.168.0.26

Conclusion

You are now ready to start your Kubernetes setup. It is important that you know how to access the nodes independently and that you can reach them both via SSH keys and as a root user.

Leave a comment if you have any questions. The next step will be installing dependencies on the nodes. Happy coding.

First published in my LinkedIn newsletter, Built from Scratch.

If it was useful, subscribe for the next one. No spam, unsubscribe anytime. If you are building something similar and want to compare notes, say hello. I read every message.

Built from scratch, like everything here.

Raspberry Pi Kubernetes Cluster: OS Installation (Issue #2)

Jules — Wed, 29 Jul 2026 12:59:20 +0000

Welcome to the Raspberry Pi Kubernetes home lab series. A bite sized informative guide to help you provision a cluster from scratch.

1. Install Ubuntu on a Raspberry Pi

The Raspberry Pi nodes are provisioned using Ubuntu 22.04 LTS for ARM. Download and unzip the image from the link.

2. Locate the SD card

Diskutil provides information about the formats of disks, which include disk images.

diskutil list

3. Unmount the disk

diskutil unmountDisk /dev/disk2

Unmount the disk so you can write onto it. Note that unmount is not the same as eject. Unmount means to remove the connection to the disk internally; eject means to physically remove it.

4. dd the image into the disk

sudo dd if=<path-to-image>/raspbian.img of=/dev/rdisk2 bs=1m

It is important that you set the block size read/write buffering to optimise the overall time of the task.

5. Enable SSH

touch /Volumes/system-boot/ssh

SSH needs to be enabled so we can talk to the nodes later.

6. Unmount and eject/remove the card

diskutil unmountDisk /dev/disk2

Leave a comment if you have any questions. We will be installing and preparing the nodes next, first manually and then in an automated fashion via Ansible. Happy coding.

First published in my LinkedIn newsletter, Built from Scratch.

If it was useful, subscribe for the next one. No spam, unsubscribe anytime. If you are building something similar and want to compare notes, say hello. I read every message.

Built from scratch, like everything here.

Raspberry Pi Kubernetes Cluster: NFS Storage (Issue #5)

Jules — Wed, 29 Jul 2026 12:58:44 +0000

Welcome to the Raspberry Pi Kubernetes home lab series. A bite sized informative guide to help you provision a cluster from scratch. By now we should have our k8s cluster up and running; great job everyone.

Today's issue will walk you through installing and creating a Network File System (NFS) server so it can be used as our default cluster storage.

1. Requirements

1 k8s cluster
1 external hard drive

2. Locate the hard drive

Plug your hard drive into one of your slave nodes and SSH into it to find its location.

sudo lsblk -o UUID,NAME,FSTYPE,SIZE,MOUNTPOINT,LABEL,MODEL

3. Format the hard drive with mkfs.ext3

We can see that our hard drive is located at /dev/sda2. Let's go ahead and format the hard drive's filesystem so it can be used by the Linux system. Other examples include /dev/sdb2.

sudo mkfs.ext3 -L k8s-volume /dev/sda2

4. Create a directory for the volume and mount it

This could be in any location. We are going to "namespace" it under k8s-mount and label it k8s-volume-1.

sudo mkdir -p /k8s-mount/k8s-volume-1
sudo mount /dev/sda2 /k8s-mount/k8s-volume-1 # mount disk

5. Install the NFS server

sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get install nfs-kernel-server -y

6. Start the server

sudo systemctl start nfs-server
sudo systemctl status nfs-server # verify it is running

7. Allocate permissions

In order to have access to your NFS server we need to create some read/write permissions.

# owner (read/write) group (read)
sudo find /k8s-mount/k8s-volume-1/ -type d -exec chmod 755 {} \;
sudo find /k8s-mount/k8s-volume-1/ -type f -exec chmod 644 {} \;
sudo find /k8s-mount/k8s-volume-1/ -type f -exec chmod 777 {} \;

8. Set up remote access

The line below will give permissions to all hosts in the network, so be careful!

sudo nano /etc/exports

/k8s-mount/k8s-volume-1/ *(rw,sync,no_subtree_check,insecure)

We can set the permissions to be restrictive per host. Let me know if you would like to see how this is done. In the meantime, here is a walk through of this setup and the official docs too.

9. Export the etc config

sudo exportfs -ra # export config
sudo exportfs -v  # see current config
showmount -e      # see what is being exported

10. Install the NFS client on all the other worker nodes

# ssh ubuntu@192.168.0.xx # WORKER_NODE
sudo apt install nfs-common -y

11. Create volume manifests

# system-volume.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: system-volume
  labels:
    name: system-volume
---
apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv-k8s-volume-1
  labels:
    type: local
spec:
  storageClassName: k8s-volume-1
  capacity:
    storage: 1Ti
  accessModes:
    - ReadWriteMany
  nfs:
    server: 192.168.0.26
    path: /k8s-mount/k8s-volume-1
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: pvc-k8s-volume-1
spec:
  storageClassName: k8s-volume-1
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 1Ti

12. Apply the manifests

kubectl apply -k path-to-manifest.yaml
kubectl --namespace system-volume get pv,pvc

Bonus

This isn't a required section but more of an educational addendum. Since we have given global access to our drive, we can now access it anywhere from within the network.

1. Find nodes

nmap -sP 192.168.0.1/24 # list nodes

WORKER_NODE_1=192.168.0.24
WORKER_NODE_2=192.168.0.26 # hard drive lives here

2. Find the volume on the network

ssh ubuntu@$WORKER_NODE_1 # a worker node

sudo apt install nfs-common

showmount -e $WORKER_NODE_2 # see what is being exported

# output
Export list for 192.168.0.26:
/k8s-mount/k8s-volume-1 *

3. Access the hard drive

sudo mkdir -p /test
sudo mount -t nfs $WORKER_NODE_2:/k8s-mount/k8s-volume-1 /test/
ls -al /test/ # inspect drive

4. End of test

Clear the test area by removing the files created previously.

sudo umount /test
sudo rm -rf /test

We are now ready to start using our local storage. It is important that you know how to access the nodes independently and that you understand how to manipulate the NFS server across the network.

Leave a comment if you have any questions. We will be integrating with MetalLB's load balancer next. Happy coding.

First published in my LinkedIn newsletter, Built from Scratch.

If it was useful, subscribe for the next one. No spam, unsubscribe anytime. If you are building something similar and want to compare notes, say hello. I read every message.

Built from scratch, like everything here.

Raspberry Pi Kubernetes Cluster: Load Balancer (Issue #6)

Jules — Wed, 29 Jul 2026 12:58:08 +0000

Welcome to the Raspberry Pi Kubernetes home lab series. A bite sized informative guide to help you provision a cluster from scratch. Our cluster should now be up and running and we should be able to easily provision services, deployments, volumes, and so on.

Today's issue will walk you through exposing a service to an external IP address.

The challenge with bare metal

Since our cluster is running on bare metal we don't have the luxury of provisioning an external load balancer. Kubernetes doesn't provide a direct implementation for network load balancers and instead comes with built-in functionality to integrate with different cloud providers (AWS, GCP, Azure, and so on). This is normally done by allowing Kubernetes to automatically create load balancers on your cloud provider. Without the ability to load balance traffic we are left with two options, "NodePort" and "ClusterIP", which are solutions better suited for internal network or cluster communication.

In this lab we will be implementing MetalLB, a solution that offers network balancing so that external traffic and services can communicate with our cluster.

1. Requirements

1 k8s cluster with a compatible CNI

2. Preparation

Please check the compatibility matrix before you implement MetalLB. If you are following this series you would have installed Flannel and therefore are good to go! Kubernetes CNI integrations are very interesting and worth a read in their own right. Calico, for example, has a really interesting implementation and is definitely worth exploring.

3. Installation

Version 0.13.5 has come a long way; integrating with MetalLB is incredibly simple. We will resource this latest version and supply a configuration file along with it.

kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: metallb-system
resources:
  - github.com/metallb/metallb/config/native?ref=v0.13.5
  - config.yaml

MetalLB is set up as an L2 balancer by default and will be idle until configured. The easiest deployment is probably the Layer 2 configuration, which works by responding to ARP requests and providing the machine's MAC address to clients.

As a bare minimum (no pun intended) it will expect a pool of available addresses in your network, and a reference for them. From the network perspective it is represented as if the cluster had multiple IPs assigned to its network interface. As you can see from the configuration below, we are assigning ports 100 to 250, which should be more than enough for our Raspberry Pi experiments.

config.yaml

apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
  name: first-pool
  namespace: metallb-system
spec:
  addresses:
  - 192.168.0.100-192.168.1.250
---
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
  name: advertisment
  namespace: metallb-system
spec:
  ipAddressPools:
  - first-pool

Apply the kustomization file and verify. MetalLB will create a daemon set "speaker" on every slave node, which will ensure the load balancer can reach our services, and a controller (responsible for address assignments).

# Apply
kubectl apply -k <kustomization_directory>

4. Test the load balancer

Let's deploy an nginx service and assign a load balancer to it.

kubectl run nginx --image=nginx
kubectl expose deploy nginx --port 80 --type LoadBalancer

Let's check that our service has indeed deployed and that it has been assigned an external IP.

kubectl get service

# Output
NAME            TYPE           CLUSTER-IP   EXTERNAL-IP
service/nginx   LoadBalancer   10.96.4.10   192.168.0.230

And there we go, our service is now available to the network!

Summary

We are now ready to start assigning IPs to our services. It is important that you know how Layer 2 balancers work so you can extend the basic configuration for MetalLB.

Leave a comment if you have any questions. We will be looking into provisioning Kubernetes secrets powered by git-secret next. Happy coding.

First published in my LinkedIn newsletter, Built from Scratch.

If it was useful, subscribe for the next one. No spam, unsubscribe anytime. If you are building something similar and want to compare notes, say hello. I read every message.

Built from scratch, like everything here.

Raspberry Pi Kubernetes Cluster: Equipment (Issue #1)

Jules — Wed, 29 Jul 2026 12:56:17 +0000

This is the first in a series on building a Kubernetes home lab from Raspberry Pi computers. Treat it as an informative guide rather than a tutorial. If you want the deep, step-by-step path, "Kubernetes the Hard Way" is the place to go.

Requirements

The usual Kubernetes prerequisites apply to each machine:

A compatible Linux host
At least 2GB of RAM per machine
2 or more CPUs
Full network connectivity between all nodes
A unique hostname, MAC address and product UUID per node
The required ports open between nodes
Swap disabled, so the kubelet behaves correctly

Equipment

What I used to build the cluster:

Compute: 4 x Raspberry Pi 4 (one master node and three worker nodes)
Storage: 4 x 32GB microSD cards
Networking: an Ethernet switch, a router with DHCP, and a cable per node
Power: USB-C / micro USB cables and a multi-amp USB charger
Cooling: a case with fans and heatsinks
Optional: an external hard drive for extra storage

<img src="/blog-media/raspberry-pi-kubernetes-cluster-equipment/raspberry-pi-4.jpeg" alt="Raspberry Pi 4">
<figcaption>Raspberry Pi 4</figcaption>


<img src="/blog-media/raspberry-pi-kubernetes-cluster-equipment/microsd-card.jpeg" alt="MicroSD card">
<figcaption>MicroSD card</figcaption>


<img src="/blog-media/raspberry-pi-kubernetes-cluster-equipment/ethernet-switch.jpeg" alt="Ethernet switch">
<figcaption>Ethernet switch</figcaption>


<img src="/blog-media/raspberry-pi-kubernetes-cluster-equipment/router.jpeg" alt="Router">
<figcaption>Router</figcaption>


<img src="/blog-media/raspberry-pi-kubernetes-cluster-equipment/ethernet-cables.jpeg" alt="Ethernet cables">
<figcaption>Ethernet cables</figcaption>


<img src="/blog-media/raspberry-pi-kubernetes-cluster-equipment/usb-c-cables.jpeg" alt="USB-C cables">
<figcaption>USB-C cables</figcaption>


<img src="/blog-media/raspberry-pi-kubernetes-cluster-equipment/usb-charger.jpeg" alt="USB charger">
<figcaption>USB charger</figcaption>


<img src="/blog-media/raspberry-pi-kubernetes-cluster-equipment/cluster-case.jpeg" alt="Cluster case">
<figcaption>Cluster case</figcaption>


<img src="/blog-media/raspberry-pi-kubernetes-cluster-equipment/external-hard-drive.jpeg" alt="External hard drive">
<figcaption>External hard drive</figcaption>

A good case with proper cooling makes a real difference once the nodes are under load, so it is worth following an assembly guide for the heatsink and fan setup.

What comes next

Later issues in the series cover configuring the nodes, SSH access, initialising the cluster, storage, and load balancing.

First published in my LinkedIn newsletter, Built from Scratch.

If it was useful, subscribe for the next one. No spam, unsubscribe anytime. If you are building something similar and want to compare notes, say hello. I read every message.

Built from scratch, like everything here.