DEV Community

From Kubernetes to a Self-Healing, Low-Cost Infrastructure

Bruce Mcpherson — Mon, 22 Jun 2026 12:20:53 +0000

I've been running a background project on Kubernetes for a while now. It's not a project that needs 100% uptime, and neither is it one I wanted to spend a lot of time managing or even checking up on, so Kubernetes with Spot VM's seemed the most cost effective solution, and it's been solid and trouble free. However running a couple of pre-emptible nodes with a managed ingress was still costing $150 a month or so. Way too much for a hobby project.

This article is about retaining the self healing capability you get with Kubernets, but migrating to a much more cost effective (about $40 a month) approach. I found that without Kubernetes in the the mix, i could get away with a single VM, but of course that doesn't give me recovery from pre-emption, so here's how to get that too.

Managed instance group

The transition from a high-cost Google Kubernetes Engine (GKE) cluster to a single, highly available Spot VM managed by a Stateful Managed Instance Group (MIG) offers a path to significant cost savings without sacrificing resilience. By leveraging Docker Compose and automated infrastructure orchestration, the platform—comprising microservices such as GraphQL gateways, Elasticsearch processors, and Redis queues—now operates at the lowest possible compute cost while maintaining full recovery capabilities.

Decoupling Compute from State

The core challenge with using Spot VMs is their preemptible nature. To make this architecture immune to data loss during preemption, it utilizes GCP Stateful MIG Policies alongside stable device-id path targeting.

A critical component of this decoupling is Storage State Preservation. Standard attachment targets (like /dev/sdb) are prone to swapping order during VM initialization. To guarantee consistency across machine replacements, the persistent volume is targeted via its unchangeable physical serial header: /dev/disk/by-id/google-existing-data.

The Autonomous Recovery Workflow

When Google Cloud preempts a Spot VM, the system triggers a fully automated self-healing pipeline:

Detection & Provisioning: The MIG detects the deletion and instantly provisions a fresh instance node to maintain the target capacity of one.
Stateful Attachment: The MIG automatically binds the regional static IP and hot-plugs the persistent block storage to the new node at boot time.
Guest OS Bootstrapping: A custom startup-script.sh holds execution until hardware attachment is verified. It then mounts the filesystem, installs the Docker Engine, and restarts microservices seamlessly using ./start-all.sh.

This entire process typically brings the platform back online with zero manual intervention within 60–90 seconds.

Operational States: Preemption vs. Scaling Down

It is vital to distinguish between a True Spot Preemption and a Manual Scale Down to 0.

Spot Preemption: The MIG's intent is to keep one machine online. Per-instance configurations are preserved, and the recovery is fully autonomous.
Scale Down to 0: This decommission command destroys the unique stateful metadata ties. When scaling back to 1, the new VM will get stuck in a boot loop because the MIG no longer knows to attach the existing disk or IP. Recovery in this scenario requires a manual orchestration script, ./create-mig.sh, to re-bind the regional static IP and existing data disk.

Comparing Infrastructure Models

Aspect	Kubernetes (GKE)	Standalone VM	Stateful MIG
Compute Cost	High (Cluster + Nodes)	Medium (Standard VM)	Lowest (Spot VM)
Preemption Recovery	Automatic	Manual Recreate	Fully Automatic
Volume Mounts	PVCs with GCE PD	Local Static /dev/sdb	Stable by-id path
IP Persistence	K8s LoadBalancer	Bound to Instance	Preserved via Config

Docker-compose benefit

Previously I was using kubernetes, cloud build and the artifact registry to manage my builds and releases. This meant that testing was a bit awkward, involving minikube, ngrok and various other workaraounds. Now that I've transitioned to docker compose, the exact same scripts and yaml files work both locally on my mac and on my vm, so i have a complete end to end simulation locally.

Replacing the Kubernetes Ingress

If you need to access the VM externally, you're going to need to create some kind of ingress. Under GKE I was using a managed ingress, with letsencrypt handling the ssl certificate. On our vanilla VM, we can use a traefix proxy. All my services run on docker, as does the traefik proxy. Here's how to set it up.

start-traefik.sh

#!/bin/bash

GREEN='\033[0;32m'
YELLOW='\033[1;33m'
RED='\033[0;31m'
NC='\033[0m'
if [[ "$(uname)" == "Darwin" ]]; then
    echo "Skipping Traefik on Mac (not needed)"
    exit 0
fi

echo -e "${GREEN}🚀 Starting Traefik...${NC}"

# Ensure network exists
docker network create fid-network 2>/dev/null

# Start Traefik
docker compose -f docker-compose-traefik.yml up -d

sleep 3

if curl -s -o /dev/null -w "%{http_code}" http://localhost:80 | grep -q "200\|301\|302"; then
    echo -e "${GREEN}✅ Traefik is running${NC}"
    echo ""
    echo "Traefik is listening on ports 80 (HTTP) and 443 (HTTPS)."
    echo "Check logs: docker compose -f docker-compose-traefik.yml logs -f traefik"
else
    echo -e "${RED}❌ Traefik may not be ready. Check logs.${NC}"
fi

docker-compose-traefik.yml

services:
  traefik:
    image: traefik:v3.2
    container_name: fid-traefik
    command:
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--providers.file.directory=/etc/traefik/conf"
      - "--certificatesresolvers.letsencrypt.acme.httpchallenge=true"
      - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"
      - "--certificatesresolvers.letsencrypt.acme.email=admin@xliberation.com"
      - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--entrypoints.web.http.redirections.entrypoint.permanent=true"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./conf:/etc/traefik/conf
      - traefik_certs:/letsencrypt
    networks:
      - fid-network
    restart: unless-stopped

volumes:
  traefik_certs:

networks:
  fid-network:
    external: true

Some example scripts

All of this is a little tricky and precise, so here are some scripts I have used to get my services running, along with a few hints. I'll assume you already have a reserved static address (if you need to expose publicly)

Your startup script (startup-script.sh)

This is mine - note the connection string that uses the by-id path. google-exisiting-data refers to the persistent disk it should attach. This is not the disk name (in my case that name is fid-data), but a standard name that a mig applies to an incoming state fule disk attachment. Note the subsequent mount command that mounts the disk as its correct name. The systemd platform file describes what to do once all that is complete. I have a start-all.sh there that will actually start all my services using the persistent disk fid-data.

#!/bin/bash
set -e

# --- 1. Wait for persistent disk to physically attach ---
echo "Waiting for persistent disk to attach..."
while [ ! -e /dev/disk/by-id/google-existing-data ]; do
    sleep 1
done

# Give the storage driver a brief moment to stabilize the block mapping
sleep 2

# --- 2. Mount persistent disk ---
mkdir -p /mnt/disks/fid-data
if ! mountpoint -q /mnt/disks/fid-data; then
    mount -o discard,defaults /dev/disk/by-id/google-existing-data /mnt/disks/fid-data
fi

# --- 3. Create symlink to repo on persistent disk ---
mkdir -p /home/brucemcpherson
chown -R brucemcpherson:brucemcpherson /home/brucemcpherson
ln -sf /mnt/disks/fid-data/fidmaster /home/brucemcpherson/fidmaster

# --- 4. Install Official Modern Docker Engine & Compose ---
apt-get update -qq
apt-get install -y -qq ca-certificates curl gnupg

# Add Docker's official GPG key and repository
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor --yes -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install the exact modern packages (restores "docker compose" with a space)
apt-get update -qq
apt-get install -y -qq docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# --- 5. Configure Docker data root ---
if ! grep -q '"data-root": "/mnt/disks/fid-data/docker"' /etc/docker/daemon.json 2>/dev/null; then
    echo '{"data-root": "/mnt/disks/fid-data/docker"}' | tee /etc/docker/daemon.json
    systemctl restart docker
fi

# --- 6. Create systemd service file ---
# Using 'tee' inside the script ensures no root permission redirection blocks
cat << 'EOF' | tee /etc/systemd/system/fid-platform.service > /dev/null
[Unit]
Description=FID Platform (all services)
After=docker.service network.target
Requires=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
User=brucemcpherson
WorkingDirectory=/home/brucemcpherson/fidmaster/vm-docker/local-compose
ExecStartPre=/bin/sleep 5
ExecStart=/bin/bash /home/brucemcpherson/fidmaster/vm-docker/local-compose/start-all.sh
ExecStop=/bin/bash /home/brucemcpherson/fidmaster/vm-docker/local-compose/stop-all.sh
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable fid-platform

# --- 7. Start all services ---
cd /home/brucemcpherson/fidmaster/vm-docker/local-compose
./start-all.sh

echo "Startup complete."

Create a managed group template

Note that the template references this startup-script. If you subsequently change the startup-script, you'll need to replace the template.

gcloud compute instance-templates create fid-vm-template-ephemeral \
    --region=europe-west2 \
    --machine-type=e2-standard-4 \
    --image-family=debian-12 \
    --image-project=debian-cloud \
    --boot-disk-size=50GB \
    --boot-disk-type=pd-ssd \
    --provisioning-model=SPOT \
    --metadata-from-file startup-script=startup-script.shgcloud

Create a managed group (create-mig.sh)

The size=1 means i want a single VM. This VM will be called your_mig_name-random_chars.

#!/bin/bash

# 1. Define your known environment variables
PROJECT_ID="your project"
REGION="europe-west2"
ZONE="europe-west2-b"
MIG_NAME="the name for your new mig"
IP_NAME="your static ip name"
DISK_NAME="your persistent disk name"

# Check if the MIG already exists before trying to create it
if gcloud compute instance-groups managed describe "$MIG_NAME" --zone="$ZONE" >/dev/null 2>&1; then
    echo "Managed Instance Group '$MIG_NAME' already exists. Skipping creation..."
else
    echo "Creating Managed Instance Group '$MIG_NAME'..."
    gcloud compute instance-groups managed create "$MIG_NAME" \
        --zone="$ZONE" \
        --template=fid-vm-template-ephemeral \
        --size=1

    # Give GCP a moment to spin up the instance before querying it
    echo "Waiting 15 seconds for instance to initialize..."
    sleep 15
fi

# 2. Automatically grab the dynamic instance name
INSTANCE_NAME=$(gcloud compute instances list --filter="name~'^fid-mig-'" --format="value(name)")

# Safety check: Ensure an instance actually exists
if [ -z "$INSTANCE_NAME" ]; then
    echo "Error: No running instance found starting with '$MIG_NAME-'."
    exit 1
fi

echo "Found target instance: $INSTANCE_NAME"

# 3. Handle the per-instance config cleanly (Create if missing, update if exists)
echo "Configuring stateful IP and Disk resources..."

if gcloud compute instance-groups managed instance-configs describe "$MIG_NAME" --instance="$INSTANCE_NAME" --zone="$ZONE" >/dev/null 2>&1; then
    CONFIG_ACTION="update"
else
    CONFIG_ACTION="create"
fi

gcloud compute instance-groups managed instance-configs $CONFIG_ACTION "$MIG_NAME" \
    --zone="$ZONE" \
    --instance="$INSTANCE_NAME" \
    --stateful-external-ip interface-name=nic0,address=projects/"$PROJECT_ID"/regions/"$REGION"/addresses/"$IP_NAME" \
    --stateful-disk=device-name=existing-data,source=projects/"$PROJECT_ID"/zones/"$ZONE"/disks/"$DISK_NAME",auto-delete=never

# 4. Trigger the MIG to apply these stateful settings to the live VM
echo "Applying configurations to $INSTANCE_NAME..."
gcloud compute instance-groups managed update-instances "$MIG_NAME" \
    --zone="$ZONE" \
    --instances="$INSTANCE_NAME"

echo "Done! Dynamic setup complete."#!/bin/bash

Ssh to your instance (ssh.sh)

My mig group is called fid-mig, so i can extract the instance name and attach to it like this.

gcloud compute ssh $(gcloud compute instances list --filter="name~'^fid-mig-'" --format="value(name)") --zone=europe-west2-b

Simulate a pre-emption to test (simulate-preemption.sh)

In this case, just deleting the instance will simulate a preemption. It will come back up and execute your startup without needing intervention. This differs from the deliberate resizing the MIG to 0 which would need manual intervention to restart the VM.


# 1. Find the current instance name
INSTANCE_NAME=$(gcloud compute instances list --filter="name~'^fid-mig-'" --format="value(name)")

# 2. Simulate a sudden crash/preemption by deleting the instance body directly
gcloud compute instances delete $INSTANCE_NAME --zone=europe-west2-b --quiet

gcloud compute instance-groups managed list

Take down the VM (down-mig.sh)

If you're not using it, might as well save the cost. All you have to do is set the Mig size to 0.

gcloud compute instance-groups managed resize fid-mig \
    --size=0 \
    --zone=europe-west2-b \
    --quiet

gcloud compute instance-groups managed list

Bring up the VM (up-mig.sh)

Setting the size to 1, will reinstate the vm. However at this point it knows nothing about what it's supposed to do, so you also need to run create-mig.sh to get back to a running system.

gcloud compute instance-groups managed resize fid-mig \
    --size=1 \
    --zone=europe-west2-b \
    --quiet

gcloud compute instance-groups managed list

links

article
video

Human Attention is a Scarce Resource

Rizèl Scarlett — Mon, 22 Jun 2026 12:20:08 +0000

I recently chatted with a Distinguished Engineer about how he uses agents in his engineering workflow and how he builds new team processes around AI-generated work.

// Detect dark theme var iframe = document.getElementById('tweet-2068069283184144450-524'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=2068069283184144450&theme=dark" }

During the conversation, David Fowler made a really poignant take: when producing code becomes trivial, human attention becomes scarce resource. 🤯

You can listen to our full conversation on Spotify. (It's a recording of a Twitter Space I did with him. People have said they really enjoyed the spaces I run, so I saved them as lightly edited podcast episodes).

See below for my own thoughts on code review in the world of agentic coding:

My own thoughts

For decades, software engineering has relied on a foundational necessity: a reliable paper trail. As version control matured from changelogs to CVS to modern Git diffs, we built our craft around durable artifacts that preserve intent, track progress, and safeguard quality.

Historically, this system worked because software development operated at human speed. An engineer reasoned through a problem, committed code, and opened a pull request. Colleagues reviewed that code, engaging in a back-and-forth dialogue to unpack the underlying logic. We deliberately used this collaborative friction to maintain code quality.

But today, a new class of autonomous collaborators has disrupted the traditional engineering workflow.

Coding agents have drastically compressed the implementation window from typing code line-by-line to writing a single prompt that generates a full feature. The most forward facing teams are already moving past single-agent execution, orchestrating parallel sessions where a main agent manages subagents to complete larger bodies of work on demand. (When I worked at Block, this became the way many teams I encountered worked).

This sudden leap in speed is intoxicating, but it threatens to outrun our ability to keep software trustworthy. In practice, an engineer uses an agent to generate hundreds of lines, but the engineer only skims the results. Reviewers facing a growing backlog do the same. If the Git diff looks right, the team ships. Then a production outage occurs. In the past, you could bring the authoring engineer into the incident room to trace their logic and patch the system. But when the decision was made by one of a dozen subagents running in parallel, there is no one to bring in, and the commit history shows only the result, not the reasoning.

This is the central problem I keep seeing in AI-native development: we can now produce code faster than we can understand it. And yet, for an industry obsessed with artifacts, meticulously tracking commits, pull requests, and logs, we often throw away the one record that explains all of them: the agent session itself.

The company I work at, Entire, has been aiming to maintain velocity without sacrificing engineering integrity by preserving agent sessions alongside the tools developers already use. The full chain of AI-assisted work, including prompts, responses, tool calls, subagent activity, checkpoints, and the final commit, can all become part of the engineering context. The mechanics do not have to be heavy. We do this using lightweight hooks around the agent and Git workflow.

But the purpose of capturing session history is not for users to simply reread a diary of logs and transcripts. (A lot of people tell me, "So what, I don't want to read the logs!") Instead, session history can become an active surface for understanding, unlocking capabilities that standard Git diffs simply cannot support.

When an engineer or agent needs to understand a complex block of autonomous code, the investigation should not stop at a timestamp, a commit hash, or a best guess. I want to be able to ask why this implementation exists, what prompt produced it, which agent or subagent touched it, and what validation or review context shaped the final result.

If we want to build at this new speed without losing our grip on the codebase, a static diff of the final code is no longer enough. When the system breaks at 2:00 AM, we cannot rely only on tools built for a human pace to audit agent-to-human collaboration. To keep our systems reliable, we have to preserve more of the actual narrative of how the software came to be.

Because in an AI-native world, the session is the story.

Check us out on entire.io !

And check out this episode of a crazy time I was on an AI coding game show for CodeTV . I look back at this episode many times, and just think "Ugh, we should've used Entire. It would've made handing off work between my team so much easier."

What's Actually in My AGENTS.md

Mitesh Sharma — Mon, 22 Jun 2026 12:18:07 +0000

The instruction file that runs my codebase started as a junk drawer. The rules that ended up mattering weren't the ones I expected.

A note on credit before I start: most of what follows isn't original to me. I picked up these ideas from other engineers sharing what worked for them — scattered across Twitter/X threads, blog posts, and conversations — then tested them against my own codebase to see what actually held up. This is a synthesis, not an invention. Where something came from the community rather than from me, I've tried to say so. Consider it a thank-you to everyone quietly posting what they've learned.

The first time I wrote an AGENTS.md, I treated it like a README's annoying cousin. Tech stack, a few style notes, a line begging the agent to run the tests. Then I watched the agent ignore half of it and confidently do the wrong thing with the other half.

So I kept editing. Months later, the file looks nothing like where it started. And the surprising part is which rules earned their place. It wasn't the formatting conventions or the careful style guidance. It was a small number of rules that fight an agent's worst instincts, plus one hard lesson about the difference between asking and enforcing.

Here's what I found actually mattered.

The first rule isn't about code. It's about permission to stop.

The very first thing in my file has nothing to do with syntax. It tells the agent that when something is unclear, it should stop and ask. State your assumptions. If two interpretations exist, name both instead of silently picking one. If a simpler approach exists, say so.

I put this first because the default failure mode of a coding agent isn't bad code. It's confident code built on a wrong reading of an ambiguous request. Left alone, a model resolves ambiguity quietly and keeps going, and you don't find out until you're reviewing two hundred lines that solve the wrong problem.

What surprised me was that the agent needed permission to stop. Without it, the model optimizes for looking helpful, and looking helpful means producing something rather than admitting confusion. Telling it that stopping to ask is the desired outcome — not a failure — changed its behavior more than any other single line.

The lesson generalized: an agent will fill silence with confidence unless you tell it that "I'm not sure" is an acceptable answer.

Most of the useful rules just name a bad habit and forbid it

Once I started paying attention, I noticed that my most valuable rules all had the same shape. Each one named a specific, predictable bad instinct and told the agent not to do it. None of them were clever. They were just earned.

Agents over-build. Ask for a function and you can get a configurable framework with options nobody requested. So one rule is blunt about it: minimum code that solves the problem, nothing speculative, and if you wrote two hundred lines where fifty would do, rewrite it. Naming the tax is what keeps it from being paid.

Agents over-reach. An agent that helpfully reformats the whole file alongside its actual change turns a ten-line diff into a two-hundred-line one you can't safely review. So another rule constrains the blast radius: touch only what you must, match the existing style even if you'd do it differently, and make every changed line trace back to the request. This one is really about protecting review, not code. A diff you can't read is a diff you can't trust.

The rule I'd most recommend stealing is one I didn't appreciate until it bit me. When an agent finds two competing patterns in a codebase, its instinct is to find a middle path that honors both. The result belongs to neither pattern and confuses everyone who reads it later. So the rule is: don't average conflicting patterns. Pick one, explain why, flag the other for cleanup. Average code that satisfies two contradictory rules is the worst code in the repo.

There's a companion to all of these that I keep coming back to: if the agent can't explain why existing code is shaped the way it is, it should ask before adding next to it. "Looks unrelated to me" is the most expensive assumption in any mature codebase. Most subtle breakages come from changes that looked perfectly isolated to the person making them.

The lesson that reshaped the whole file

If I could keep only one thing I learned, it's this, and it took the longest to accept.

I once had a hard requirement written in plain, unmissable language at the top of the file. The agent still skipped it sometimes. Not often — just often enough to cause real problems. When I dug into why, the answer was deflating in its simplicity: models drift from instructions. A rule in a markdown file is a strong suggestion, not a contract. Over enough runs, any instruction gets ignored eventually.

That one realization split my entire file into two tiers.

There's guidance — the style preferences, the philosophy, the "prefer this over that." Guidance lives in prose and gets followed most of the time, and most of the time is fine for that category.

Then there's the stuff that has to hold every single time. And what I learned is that this stuff does not belong in prose at all. If something absolutely must happen, don't rely on instructions. Enforce it. Put it in a hook, a script, a CI check — something deterministic that makes the violation impossible to merge, not merely discouraged.

My file still says "run the checks before you call it done." But the real guarantee isn't that sentence. It's that CI fails on lint errors no matter what the agent intended. The instruction is a courtesy. The gate is the guarantee.

The practical test I use now: every time I write "always" or "never" in an instruction file, I ask whether there's a mechanism enforcing it. If there isn't, I don't have a rule. I have a hope.

Make the agent prove it, not promise it

Two more rules in the file are really about the gap between "I did it" and "it works."

The first changes how a task is framed. Instead of "add validation," the instruction is to define what success looks like and loop until it's met: write tests for the invalid inputs, then make them pass. "Fix the bug" becomes "write a test that reproduces it, then make it pass." A vague directive becomes one with a finish line the agent can check itself against, instead of declaring victory on vibes.

The second is blunt about trust: don't claim tests pass from memory — re-run them. I added this after watching the agent report a clean run that wasn't, and after watching sub-agent reviews invent bugs that didn't exist in the source. Both are the same failure: a claim untethered from a fresh check. So the rule ties every claim back to a command actually run, and tells the agent to verify a reported bug against the real code before acting on it.

The principle underneath both: trust the check, not the claim. An agent's confidence is not evidence.

Keep the laws out of the manual

One structural decision kept the whole file maintainable: my AGENTS.md doesn't try to contain the architecture.

The structural laws — dependency direction, frozen contracts, the boundaries that can't be crossed — live in a separate constitution document. The working file just points at it: read this before you add a package, cross a layer, or touch anything safety-critical. And it's explicit that if a change conflicts with the constitution, the move is to refactor or open an amendment, never to slip in a violation to ship faster, because that cost compounds.

The reason to separate them is pace. The working manual is full of conventions and gotchas that change constantly and should be edited freely. The constitution holds laws that should be slow to change and mechanically enforced. Cram both into one file and the stable laws get buried under operational churn. Keep them apart, and each can move at its own speed.

The takeaway: things that change weekly and things that should never change don't belong in the same document.

Write down the scars

The back half of my file is the part I'd most encourage every team to keep: a running log of non-obvious lessons. Not conventions — scars. The specific things that cost someone half a day and would cost the next person the same half-day if they weren't written down.

They're deliberately concrete. The database pseudo-column that isn't selected by default, and the exact error you get when you forget it. The streaming API that keys its events by index instead of ID and arrives in a surprising order. The native dependency that silently fails to compile unless it's on an allowlist. None of these are principles. They're landmines, mapped.

This section matters more with agents than it ever did with people, because an agent has no scar tissue. A human who lost a day to something tends to remember it. An agent will rediscover the same landmine the hard way every single time, unless the knowledge is written where it'll read it. That's the quiet value here: it's how a codebase's painful, accumulated knowledge gets inherited instead of relearned.

Every unexpected hour you lose is only worth paying once. Writing it down is how you make sure of that.

What the file is really for

After all the editing, here's how I think about it now. This file isn't a style guide. The formatter handles tabs and semicolons. What the file actually does is encode judgment — the judgment that used to live only in the heads of the few people who'd been around long enough to have it.

The rules that matter are the ones that counteract an agent's predictable instincts: over-building, over-reaching, guessing silently, blending conflicting patterns, claiming success it never verified. And the most important distinction in the whole file is the line between guidance you state and guarantees you enforce.

So if you're writing one of these, that's where I'd spend the effort. Give the agent permission to stop and ask. Name the bad habits you keep seeing and forbid them by name. Move anything that must always hold out of prose and into a check that fails the build. Point at your architecture instead of restating it. And keep a growing log of your scars, because the agent will step on every landmine you don't map.

The formatting rules write themselves. The judgment is the part worth writing down.

Hardening Unattended Raspberry Pi Edge Nodes: Watchdog, fail2ban, nftables, and the Mistakes That Take Down DNS

david — Mon, 22 Jun 2026 12:14:01 +0000

Originally published at woitzik.dev

Two Raspberry Pi 4Bs run AdGuard Home and Unbound for an entire home network, in an active/passive pair via Keepalived. They're physical hardware sitting on a shelf, not VMs or LXCs — no Proxmox snapshot, no PBS backup, no terraform destroy && apply to recover from a bad state. If one hangs hard at 2am, nobody notices until someone's phone can't resolve a hostname.

This is the hardening pass that closed every gap I found in that setup: a hardware watchdog for total-system-freeze recovery, fail2ban for the one SSH-exposed surface, an nftables host firewall that's careful not to fight with Docker's own iptables rules, log size caps to stop slow SD-card death, and a DNS health check that works even on the day the rest of the monitoring stack is offline — which, as it turned out, was exactly the day it mattered.

View the complete homelab infrastructure source on GitHub 🐙

Why "It's Just DNS" Needs More Hardening, Not Less

The instinct with a small, single-purpose device is to leave it alone — fewer moving parts, fewer ways to break it. That's backwards for a device with no operator watching it and no automated recovery path. A k3s pod that crashes gets rescheduled in seconds. A Raspberry Pi that hard-hangs stays hung until a human walks over and pulls the power.

Everything below is about closing that gap: detecting failure independently, recovering from total freezes without intervention, and not introducing a new failure mode in the process of doing any of this.

Hardware Watchdog: Recovering From a Hang Software Can't See

A crashed container gets restarted by Docker. A kernel deadlock — the whole system stops responding, nothing crashes, nothing logs anything — doesn't. Nothing is left running to notice the problem or act on it.

The Broadcom SoC in a Raspberry Pi has a hardware watchdog timer: a circuit that resets the board if it isn't periodically "petted." As long as something pets it, the system is presumed alive. If petting stops — because the kernel is deadlocked and nothing can run — the watchdog fires and power-cycles the board.

# /boot/firmware/config.txt
dtparam=watchdog=on

# /etc/systemd/system.conf
RuntimeWatchdogSec=15s
RebootWatchdogSec=10min

RuntimeWatchdogSec=15s means systemd pets the hardware watchdog every 15 seconds while the system is healthy. If systemd itself stops running (the actual deadlock case this exists for), the pets stop, and the watchdog circuit force-resets the board. RebootWatchdogSec=10min is a second, independent safety net — if a reboot itself hangs (stuck somewhere in shutdown), the watchdog fires again after 10 minutes rather than leaving the board hung mid-reboot indefinitely.

This requires a reboot to take effect — the config.txt change only applies at boot. I gated the actual reboot behind an explicit flag (rpi_optimize_reboot, default false) rather than auto-rebooting a DNS server as a side effect of an Ansible run.

fail2ban: The One Exposed Surface

These Pis are reachable from the entire server VLAN, and via the Keepalived VIP, present a single consistent address that's an obvious target for anything scanning the network. The only network-facing attack surface that matters here is SSH.

# /etc/fail2ban/jail.d/sshd.local
[sshd]
enabled = true
port = ssh
filter = sshd
maxretry = 5
findtime = 10m
bantime = 1h

Five failed attempts within ten minutes bans the source IP for an hour. fail2ban only watches sshd auth logs — it has zero interaction with the DNS path (AdGuard, Unbound, Docker). That isolation matters: a misconfigured fail2ban jail watching the wrong log file, or banning based on the wrong filter, is a self-inflicted outage risk on a box where outages are expensive. Scoping it to exactly one well-understood log source keeps the blast radius of a fail2ban misconfiguration limited to "SSH access," never to DNS itself.

The nftables Trap: Don't Touch /etc/nftables.conf

This is the part that could have caused the exact outage the rest of this hardening pass exists to prevent.

The obvious way to add a host firewall on Debian is to edit /etc/nftables.conf and enable nftables.service. The problem: that file conventionally starts with flush ruleset — and Docker manages its own NAT and FORWARD chains via iptables-nft (the nftables-backed iptables compatibility layer). Enabling the stock nftables.service would flush ruleset on every boot, wiping out Docker's NAT rules along with it, and silently break every published container port. On a box running AdGuard with network_mode: host specifically so it can bind port 53 directly — but also running other containers in bridge mode with published ports — that's not a hypothetical, it's the actual topology.

The fix: don't touch /etc/nftables.conf or the stock service at all. Use a separate ruleset file and a separate, custom systemd service:

# /etc/nftables-hostfw.conf
table inet hostfw {
  chain input {
    type filter hook input priority filter; policy drop;
    iif "lo" accept
    ct state established,related accept
    ip protocol icmp accept
    meta l4proto ipv6-icmp accept
    tcp dport 22 accept
    tcp dport 53 accept
    udp dport 53 accept
    tcp dport 3001 accept
    tcp dport { 80, 443 } accept
    udp dport 41641 accept
    ip protocol vrrp accept
  }
}

# /etc/systemd/system/hostfw.service
[Unit]
Description=Host firewall (inet hostfw table, additive — does not touch Docker's tables)
After=network.target docker.service
Wants=docker.service

[Service]
Type=oneshot
RemainAfterExit=true
ExecStart=/usr/sbin/nft -f /etc/nftables-hostfw.conf
ExecStop=/usr/sbin/nft delete table inet hostfw

[Install]
WantedBy=multi-user.target

A named table (inet hostfw) in its own namespace, with policy drop only on that table's input chain — it's additive to whatever else nftables is doing, not a replacement of the ruleset. After=docker.service and Wants=docker.service ensure ordering: this table gets applied after Docker has already set up its own rules, so there's no race where this firewall's policy drop briefly applies before Docker's accept rules for its own traffic exist.

What this firewall covers: SSH (22), DNS (53 — AdGuard runs network_mode: host, so this is genuinely host-stack traffic, not Docker-NAT'd), AdGuard's web UI (3001), the HAProxy VIP (80/443), Tailscale (41641/udp), Keepalived VRRP.

What it deliberately doesn't cover: bridge-mode containers like Unbound (5335) and node_exporter (9100). Docker DNATs traffic to these before it ever reaches the host's INPUT chain — this firewall's table never sees that traffic, confirmed by live testing, not just by reading documentation about how Docker's iptables integration works. Restricting bridge-mode container ports would require rules in Docker's own DOCKER-USER chain, with careful IPv4/IPv6 handling to avoid breaking container egress. I deferred this: MikroTik already segments these Pis from the wider internet at the network layer, and the mistake-risk of getting DOCKER-USER chain rules wrong on a live DNS server outweighed the marginal security benefit of restricting traffic that's already internal-only.

Validation that actually validates the deployment path, not just the live change: live-tested on the replica Pi first, with a systemd-run safety-rollback timer staged before every individual change (the same dead-man's-switch pattern as the MikroTik cleanup). Then re-tested via the actual Ansible run — a separate code path from the manual live test, since a playbook can have a templating bug that a manual nft -f test wouldn't catch. Then validated with an actual reboot, to confirm the systemd service correctly reapplies the ruleset on boot, rather than only working because it happened to still be live-applied from the manual test. Only after the replica was fully green did the same sequence run against the primary DNS node.

Stopping Slow SD-Card Death

Docker's default json-file log driver has no size limit. On a box with a real disk, that's eventually a problem; on a Pi with an SD card as its only storage, it's a slow-motion outage that looks like nothing is wrong until the card is full and everything stops:

// /etc/docker/daemon.json
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

Existing container logs were already at 17MB and 2.7MB by the time I checked — not catastrophic yet, but on a trajectory toward "disk full" with zero warning beforehand, months out. This setting only caps logs for containers created or recreated after the daemon restart — it doesn't retroactively truncate what's already there. Existing oversized logs needed a manual one-time cleanup; the daemon-wide default just stops the problem from recurring.

Memory Limits: Catching a Leak Before It Takes the Whole Pi Down

# docker-compose, per service
adguardhome:
  mem_limit: 512m
unbound:
  mem_limit: 256m
promtail:
  mem_limit: 256m
node_exporter:
  mem_limit: 128m
autoheal:
  mem_limit: 64m

These are generous numbers, chosen from actual observed usage with real headroom — the goal isn't to constrain normal operation, it's to make sure a genuine memory leak or runaway process in one container gets killed by Docker's OOM handling for that container before it starves every other process on the Pi, including the DNS resolver everything depends on. Tested incrementally on the replica first, verified via docker inspect that limits were actually enforced, confirmed all containers came back Up after restart, with DNS unaffected throughout — the kind of change where "looks fine" isn't sufficient confirmation on a box this important.

Local Config Backup: The Gap Nobody Noticed

These Pis are physical hardware — Proxmox Backup Server and Velero only cover VMs and LXCs, so neither one was ever backing these up. The gap had existed since the Pis were first deployed, just never surfaced, because nothing had ever required restoring from a backup yet.

#!/bin/bash
# /usr/local/bin/backup-rpi-configs.sh
set -euo pipefail
DEST=/opt/backups
STAMP=$(date +%Y%m%d-%H%M%S)
tar czf "${DEST}/configs-${STAMP}.tar.gz" \
  -C / opt/adguardhome/conf opt/unbound 2>/dev/null || true
ls -t "${DEST}"/configs-*.tar.gz 2>/dev/null | tail -n +15 | xargs -r rm --

Daily, via a systemd timer with randomized delay (to avoid both Pis hitting disk I/O at the exact same instant), keeping the 14 most recent snapshots. Deliberately local-only, with no NFS or git dependency — the NFS server runs as an LXC on the Proxmox host, and depending on the thing you're backing up away from failing defeats the purpose. AdGuard's config also contains a bcrypt password hash; pushing that into git history, even encrypted-at-rest on a private remote, is an unnecessary exposure for a snapshot whose only job is "let me recover the last known-good config after an accidental change."

Alerting That Survives the Main Alerting Stack Being Down

This is the piece that mattered in practice, not just in theory. The homelab's primary alerting path (Prometheus → Alertmanager → Discord) runs on the k3s cluster, which runs on the Proxmox host. On the day I built this, the Proxmox host itself was down for hardware repair — which meant the entire alerting pipeline was also down, on exactly the day DNS health mattered most, since DNS was now also the only thing left running unsupervised.

#!/bin/bash
# Independent DNS health check — ZERO dependency on k3s/Prometheus/Alertmanager
WEBHOOK_URL="..."
STATE_FILE="/var/lib/dns-healthcheck.state"
HOSTNAME=$(hostname)

check_dns() {
  dig +short +timeout=3 google.com @127.0.0.1 -p 53 > /dev/null 2>&1 && \
  dig +short +timeout=3 google.com @127.0.0.1 -p 5335 > /dev/null 2>&1
}

PREV_STATE="unknown"
[ -f "$STATE_FILE" ] && PREV_STATE=$(cat "$STATE_FILE")

if check_dns; then CURRENT_STATE="healthy"; else CURRENT_STATE="unhealthy"; fi

if [ "$CURRENT_STATE" != "$PREV_STATE" ]; then
  if [ "$CURRENT_STATE" = "unhealthy" ]; then
    MESSAGE="🔴 **${HOSTNAME}**: DNS resolution failing. This alert is independent of the main monitoring stack."
  else
    MESSAGE="🟢 **${HOSTNAME}**: DNS resolution recovered."
  fi
  curl -s -X POST -H "Content-Type: application/json" \
    -d "{\"content\": \"${MESSAGE}\"}" "${WEBHOOK_URL}" > /dev/null 2>&1 || true
fi

echo "$CURRENT_STATE" > "$STATE_FILE"

Run every two minutes via a systemd timer. Two design choices that matter more than the script's mechanics:

It tests both layers independently — AdGuard on port 53 and Unbound directly on port 5335. AdGuard forwards to Unbound; testing only the front door (53) wouldn't distinguish "AdGuard is fine but its upstream resolver died" from "everything's fine." && between the two dig calls means both have to succeed for the overall state to be healthy.

It only posts on a state change, not on every run. A naive healthcheck that posts every two minutes regardless of state either spams a channel into being muted (defeating the purpose) or gets its messages ignored after the first few identical ones. Tracking previous state in a file and diffing against it means the alert fires exactly twice per incident: once when it breaks, once when it recovers — and nothing in between.

The webhook URL reuses the same Discord webhook Alertmanager already posts to — found, while wiring this up, to have been committed in plaintext in the cluster's own monitoring config. Worth its own fix, but explicitly out of scope for this change; noted rather than silently expanded into a second unrelated remediation in the same commit.

What Actually Got Tested, Not Just Written

Every change here got the same validation discipline, because the box matters too much to skip it: replica first, primary only after the replica was fully green; a manual live test and a separate Ansible-driven test, since they're different code paths; and for anything that should survive a reboot, an actual reboot — not just trusting that a systemd unit file is correct.

The pattern generalizes past Raspberry Pis: any unattended edge device — a branch-office router, an IoT gateway, a remote sensor node — has the same shape of problem. No operator watching it, no automated platform-level recovery, and a failure mode (hard hang) that ordinary application-level monitoring can't see because the monitoring agent itself is also hung. A hardware watchdog plus an alerting path with zero dependency on the thing being monitored is the minimum bar for "I'll find out if this breaks," regardless of what the device actually does.

IPv6 NAT66 Behind a FritzBox: The RouterOS 7 Bug That Broke WiFi Clients

david — Mon, 22 Jun 2026 12:13:49 +0000

Originally published at woitzik.dev

Most homelab IPv6 guides assume you have native IPv6 from your ISP: a delegated /56 prefix, clean RA on the WAN, no NAT. That describes maybe 30% of actual deployments in Germany.

The other 70% sits behind a FritzBox with DS-Lite or CGN, gets a GUA on the WAN interface via SLAAC, and has no delegated prefix to distribute internally. If you want IPv6 inside your network, you build it yourself.

This is the setup I run: ULA addressing internally, NAT66 masquerade for outbound, everything Terraform-managed. It worked until RouterOS 7's router advertisement defaults caused every FritzBox WiFi client to route IPv6 through MikroTik — and then get dropped.

View the complete homelab infrastructure source on GitHub 🐙

The Topology

Internet
    │
FritzBox (CGN / DS-Lite)
    │  ether1 (WAN) — gets GUA via SLAAC from FritzBox
MikroTik RB5009
    ├── vlan10-mgmt   fd10::1/64
    ├── vlan20-srv    fd20::1/64
    ├── vlan30-dmz    fd30::1/64
    ├── vlan40-iot    fd40::1/64
    └── vlan100-admin fd64::1/64

The FritzBox provides:

IPv4 via CGN/DS-Lite (no public IPv4)
IPv6 GUA prefix via RA on its LAN port — MikroTik's ether1 picks this up via SLAAC

Internally, I use ULA (fd00::/8, RFC 4193). ULA is the IPv6 equivalent of RFC1918 private addressing. It's stable — it doesn't change when the ISP rotates the GUA prefix — and it works for all internal communication. The NAT66 rule masquerades ULA sources to the GUA when leaving ether1.

Step 1: ULA Addresses Per VLAN

Each VLAN gets a /64 from the fd::/8 space. I use the VLAN number as the second octet for readability:

# terraform/stacks/network/ipv6_network.tf

locals {
  ipv6_ula_prefixes = {
    "vlan10-mgmt"   = "fd10::/64"
    "vlan20-srv"    = "fd20::/64"
    "vlan30-dmz"    = "fd30::/64"
    "vlan40-iot"    = "fd40::/64"
    "vlan100-admin" = "fd64::/64"
  }
}

resource "routeros_ipv6_address" "vlan_ula" {
  for_each = local.ipv6_ula_prefixes

  address   = replace(each.value, "::/64", "::1/64")
  interface = each.key
  advertise = true
  comment   = "ULA gateway for ${each.key}"
}

advertise = true enables IPv6 ND (Neighbor Discovery) on each interface. Hosts on each VLAN receive a Router Advertisement with the /64 prefix and auto-configure a ULA address via SLAAC. No DHCPv6 needed.

The router address is ::1 in each /64: fd10::1/64, fd20::1/64, etc.

Step 2: Accept RA on ether1

MikroTik defaults to ignoring Router Advertisements when forward = true (i.e., when acting as a router). You have to explicitly enable RA acceptance on the WAN interface:

resource "routeros_ipv6_settings" "global" {
  accept_router_advertisements = "yes"
  forward                      = true
}

With this, ether1 accepts the RA from the FritzBox and configures its GUA via SLAAC. ip6 address print will show the GUA alongside the manually configured ULA if you have any internal IPv6 config on ether1.

Step 3: NAT66 Masquerade

The NAT66 rule masquerades outbound IPv6 from ULA sources to the GUA on ether1:

resource "routeros_ipv6_firewall_nat" "nat66_masquerade" {
  chain         = "srcnat"
  action        = "masquerade"
  src_address   = "fd00::/8"
  out_interface = "ether1"
  comment       = "NAT66: ULA → WAN GUA (FritzBox upstream)"
}

The src_address = "fd00::/8" constraint is critical. Without it, the rule matches ALL IPv6 traffic leaving ether1 — including traffic from FritzBox WiFi clients that happens to transit MikroTik. This is one half of the bug that caused problems (more on that below).

Step 4: IPv6 Firewall

The IPv6 firewall mirrors the IPv4 firewall philosophy: default-drop, explicit allows, place_before for deterministic rule ordering.

# INPUT chain
resource "routeros_ipv6_firewall_filter" "v6_in_00_established" {
  action           = "accept"
  chain            = "input"
  connection_state = "established,related,untracked"
  place_before     = routeros_ipv6_firewall_filter.v6_in_01_icmpv6.id
  comment          = "V6-IN-00: Allow established/related"
}

resource "routeros_ipv6_firewall_filter" "v6_in_01_icmpv6" {
  action       = "accept"
  chain        = "input"
  protocol     = "icmpv6"
  place_before = routeros_ipv6_firewall_filter.v6_input_drop_all.id
  comment      = "V6-IN-01: Allow ICMPv6 (NDP, RA, ping6)"
}

resource "routeros_ipv6_firewall_filter" "v6_input_drop_all" {
  action  = "drop"
  chain   = "input"
  comment = "V6-IN-DROP: Drop all other IPv6 input"
}

# FORWARD chain
resource "routeros_ipv6_firewall_filter" "v6_fwd_00_established" {
  action           = "accept"
  chain            = "forward"
  connection_state = "established,related,untracked"
  place_before     = routeros_ipv6_firewall_filter.v6_fwd_01_icmpv6.id
  comment          = "V6-FWD-00: Allow established/related"
}

resource "routeros_ipv6_firewall_filter" "v6_fwd_01_icmpv6" {
  action       = "accept"
  chain        = "forward"
  protocol     = "icmpv6"
  place_before = routeros_ipv6_firewall_filter.v6_fwd_02_internal_out.id
  comment      = "V6-FWD-01: Allow ICMPv6"
}

resource "routeros_ipv6_firewall_filter" "v6_fwd_02_internal_out" {
  action        = "accept"
  chain         = "forward"
  src_address   = "fd00::/8"
  out_interface = "ether1"
  place_before  = routeros_ipv6_firewall_filter.v6_forward_drop_all.id
  comment       = "V6-FWD-02: Allow internal ULA to WAN"
}

resource "routeros_ipv6_firewall_filter" "v6_forward_drop_all" {
  action  = "drop"
  chain   = "forward"
  comment = "V6-FWD-DROP: Drop all other IPv6 forward"
}

The forward rule v6_fwd_02_internal_out only allows ULA sources (fd00::/8) to exit via ether1. That's intentional — and it's what exposed the RouterOS 7 bug.

The Bug: RouterOS 7 Sends RA on All Interfaces

After deploying this configuration, FritzBox WiFi clients started losing IPv6 connectivity.

The symptom: devices on the FritzBox WiFi (SSID, not the MikroTik VLANs) had IPv6 addresses but couldn't reach the internet via IPv6. traceroute6 on an affected device showed the path going through MikroTik — not the FritzBox.

The cause: RouterOS 7 enables Router Advertisement on all interfaces by default, including ether1 (WAN).

Here's the sequence:

MikroTik receives a GUA prefix from FritzBox via RA on ether1
RouterOS 7 then re-advertises a Router Advertisement on ether1 — back towards the FritzBox
The FritzBox sees MikroTik advertising itself as an IPv6 router on the LAN
FritzBox WiFi clients pick up MikroTik's RA and install it as their default IPv6 gateway
IPv6 traffic from WiFi clients routes through MikroTik's FORWARD chain
FORWARD chain only accepts fd00::/8 sources — GUA addresses from WiFi clients don't match
Traffic dropped. IPv6 broken for all FritzBox WiFi clients.

The fix is to disable RA on ether1. In RouterOS /ip6/nd, find the ether1 entry and set advertise=no.

The problem: as of terraform-routeros provider version 1.99.1 (latest at time of writing), there is no routeros_ipv6_nd resource to manage this via Terraform. The fix has to be applied manually:

/ipv6/nd set [find interface=ether1] advertise=no

This is documented in the Terraform configuration as a comment so it doesn't get overwritten by a future terraform apply:

# RouterOS 7 enables RA advertisement on ALL interfaces by default — including
# ether1 (WAN). Once ether1 gets a GUA via SLAAC, MikroTik starts sending RAs
# on the FritzBox LAN. FritzBox WiFi clients then use MikroTik as their IPv6
# gateway, but the FORWARD chain only allows fd00::/8 sources → GUA clients
# are dropped → IPv6 broken on FritzBox WiFi.
# RA on ether1 is disabled in RouterOS: /ipv6/nd set [find interface=ether1] advertise=no
# routeros_ipv6_nd is not exposed in terraform-routeros/routeros ≤ 1.99.1 (latest as of 2026-06).

Once routeros_ipv6_nd is added to the provider (tracked upstream), this should be managed as:

resource "routeros_ipv6_nd" "ether1_no_ra" {
  interface = "ether1"
  advertise = false
}

ULA vs. GUA: Why Not Just Use the ISP Prefix?

The obvious alternative: use the GUA prefix the FritzBox receives from the ISP, delegate a /64 to each VLAN, and skip NAT66 entirely. IPv6 was designed to eliminate NAT.

The problem: German ISPs frequently rotate GUA prefixes. A prefix change means every device on every VLAN gets a new address — breaking DNS records, Ansible inventory, firewall rules, and anything else that references addresses directly.

ULA solves this. The fd::/8 prefix is locally assigned and never changes. Internal addressing is stable forever. The NAT66 rule handles the GUA ↔ ULA translation at the WAN boundary transparently.

The trade-off: ULA + NAT66 breaks end-to-end IPv6 reachability (GUA hosts on the internet can't initiate connections to your ULA hosts). For a homelab where all inbound connections come through a Cloudflare Tunnel or Traefik ingress anyway, that's not a problem.

Verifying the Setup

After applying the Terraform config and the manual RA fix:

# From a device on vlan20-srv (should have fd20::/64 address)
ip -6 addr show
# Should see: fd20::xxx/64

# Test outbound IPv6
ping6 -c 3 ipv6.google.com
# Should succeed (NAT66 masquerades the ULA source to the GUA)

# From a FritzBox WiFi device
ip -6 route show
# Default via should point to FritzBox, not MikroTik

If WiFi clients still route through MikroTik after setting advertise=no, run ip6/nd print on the RouterOS terminal to verify the change persisted. RouterOS can be slow to propagate ND configuration changes.

The same ULA-vs-GUA stability trade-off shows up in Azure networking — except there it's RFC1918 address space behind NAT Gateway or Azure Firewall instead of a CGN ISP. If you're designing the equivalent zero-trust network layer for Azure, the same default-deny-plus-explicit-allow philosophy applies.

npm Dependencies: How to Evaluate a Library Before Shipping It to Production

Juan Torchia — Mon, 22 Jun 2026 12:02:41 +0000

npm Dependencies: How to Evaluate a Library Before Shipping It to Production

Back in 2005, when I was 16 and managing the network at a cyber café, I learned something no manual ever taught me: every cable you plugged in was debt. If the vendor for that cable disappeared or changed the connector, the problem was yours. Not the vendor's, not the customer's. Yours. Today, when I look at a package.json with 180 direct dependencies in a TypeScript project, I think exactly the same thing. Every entry in that file is a cable someone is going to have to maintain. And in most cases, that someone is you.

My take is direct: adding an npm dependency isn't just installing code — it's assuming its maintenance, its CVE history, its transitive dependencies, and the exit cost when the library gets abandoned. The question isn't "does it work?" The question is "what happens when it stops working in six months?"

Why Evaluating npm Dependencies Is a Maintenance Decision, Not Just a Security One

The official npm documentation defines a package as "a file or directory described by a package.json" (npm docs). That's all npm guarantees as a platform: that the file exists and has metadata. Nothing about whether the author is still active, whether it has tests, whether the types are correct, or whether you'll be able to upgrade in two years without breaking half the system.

What the official docs don't say — and where people get burned — is that a published package can freeze in time. The author might not have bandwidth, might abandon the project, or might simply never hear about a relevant CVE. And at that point, the debt is yours.

There are three dimensions that matter before installing anything in a TypeScript project with pnpm:

Active maintenance: When was the last commit? Are there PRs that have gone unanswered for months? Any releases in the past year?
Attack surface and types: Does the package ship its own types (@types/) or generate them? How many transitive dependencies does it drag in?
Exit cost: If you need to rip it out tomorrow, how much of your own code changes?

How to Audit a Dependency Before `pnpm add`

The usual recipe is: search on npm, check if it has GitHub stars, install it, done. The problem is that measures popularity, not quality or longevity. Popularity and active maintenance are not the same thing.

Here's the process I use, step by step and fully reproducible:

1. Check the Real State of the Repository

Before installing, open the repo on GitHub and look at:

Last commit on main: if it's been more than 12 months with no activity and it's not a stable utility library (like lodash), that's a signal.
Open issues: Are there bugs sitting unanswered for months? CVEs mentioned but not patched?
CHANGELOG or releases: a serious project has a version history. If it doesn't, the risk surface goes up.

2. Analyze Transitive Dependencies with `pnpm why`

# Install in an isolated test project
pnpm add <package-name>

# See what it brought along
pnpm why <package-name>

# Or a full dependency tree
pnpm list --depth=3

A dependency that looks small can drag in 40 transitive packages. That's not automatically bad — but if two of those 40 have active CVEs, the problem is yours even if your own code never calls them directly.

3. Run a Security Audit From the Start

# Basic audit with npm (works on pnpm projects too)
npm audit

# To see only critical and high vulnerabilities
npm audit --audit-level=high

# If you want the JSON to process it
npm audit --json | jq '.vulnerabilities | to_entries[] | select(.value.severity == "critical")'

npm audit uses the npm Advisory Database to cross-reference installed versions against known CVEs. It's not infallible — there are vulnerabilities that don't have an advisory yet — but it's the minimum reasonable floor before committing to a dependency.

4. Verify TypeScript Types

In a TypeScript project, a dependency without types is guaranteed friction. Check:

# Does the package ship its own types?
cat node_modules/<package>/package.json | grep '"types"'

# Are @types/ available?
npm info @types/<package>

If the package doesn't ship its own types and the @types/ are community-maintained (not by the original author), you have two separate sources of drift. When the package updates and @types/ doesn't, the compiler fails in ways that aren't obvious.

5. Evaluate Exit Cost With Your Own Interface

This is the step that gets skipped the most. The question isn't just "does it work today?" but "how much code do I change if I rip it out tomorrow?"

// Pattern that reduces exit cost:
// Wrap the dependency behind your own interface

// ❌ Using the dependency directly throughout the codebase
import { parse } from 'some-date-lib'
const date = parse('2025-01-15')

// ✅ Abstracting behind your own module
// lib/dates.ts
import { parse as _parse } from 'some-date-lib'

export function parseDate(input: string): Date {
  return _parse(input) // single entry point
}

If the library is spread across 40 different files with no abstraction, removing it costs a major refactor. If it lives in one module, removing it costs an internal implementation swap.

The Most Common Mistakes When Evaluating npm Dependencies

Mistake 1: Confusing Weekly Downloads With Stability

npm download numbers include automatic mirrors, CIs, and pipelines. A library with 2M weekly downloads can have a maintainer who hasn't merged a PR in a year. Downloads are a lagging indicator of past popularity, not a guarantee of future support.

Mistake 2: Ignoring `devDependencies` in Projects With Build Steps

If a vulnerable devDependency is involved in the build (babel, webpack, esbuild, tsx), the code it generates can be compromised. The devDependencies field in package.json separates intent, not risk. If it goes through the compiler, it matters.

Mistake 3: Not Looking at `peerDependencies`

# Check what versions of React/Node the lib expects
npm info <package> peerDependencies

A library that asks for React 17 as a peer in a React 19 project might work — or it might produce silent bugs from duplicate context. Peer conflicts are one of the most common hidden costs in stack upgrades.

Mistake 4: Assuming a Small Package Is Safe

Attack surface isn't proportional to size. The event-stream incident in 2018 showed that a small utility package, transferred to a new maintainer, can become an attack vector. Small doesn't mean harmless. (Source: npm blog on the incident)

This kind of risk connects directly to what I wrote about OAuth Scope Creep: attack surface accumulates at the edges, not the center.

Decision Matrix: Do I Add This Dependency or Not?

Criterion	Green (add it)	Yellow (evaluate further)	Red (avoid or wrap)
Last release	< 6 months	6–18 months	> 18 months with no activity
TypeScript types	Bundled in the package	Active `@types/` aligned with the package	No types or outdated `@types/`
Active CVEs	None	Low severity, no public exploit	Critical or high with no patch
Transitive deps	< 10	10–40	> 40 or deps with CVEs
Exit cost	Easy to wrap	Moderate coupling	Invasive across multiple modules
Active maintainer	Responds to issues/PRs	Slow but responds	No visible activity

If a dependency lands in "Red" on more than two criteria, the right question is: do I actually need this abstraction, or can I implement the specific logic I need in 50 lines of my own code?

When working on projects with pnpm workspaces — like I described in the post about pnpm workspaces and CI on Railway — this evaluation matters twice as much: a problematic dependency in a shared package of the monorepo gets inherited by every app in the workspace.

What This Checklist Can't Guarantee

Being honest about the limits:

It doesn't predict future abandonment: a library with recent releases can get abandoned tomorrow. The checklist measures current state, not future state.
npm audit doesn't cover all vectors: business logic vulnerabilities, sophisticated supply chain attacks, and unreported CVEs don't show up in a standard audit. It's the floor, not the ceiling.
The real exit cost only gets measured in practice: estimating the cost of removing a dependency is a heuristic. Until you actually do it, it's a projection. If the project already has the dependency deeply integrated, the retrospective evaluation is more expensive than the prospective one.
GitHub metrics are indicators, not proof: an archived repository can be stable because it reached feature-complete. A repo with tons of commits can be unstable due to constant refactoring. Context matters.

FAQ: Evaluating npm Dependencies in TypeScript Projects

How many direct dependencies is "too many" in a TypeScript project?

There's no universal number. What is a warning sign is having more than 50–60 direct dependencies without having actively evaluated which ones could be replaced by your own implementations. The criterion isn't the count — it's whether every entry in dependencies has a clear reason that can't be solved in fewer than 100 lines of your own code.

Does pnpm have security advantages over npm or yarn for this kind of audit?

pnpm has a different storage model (content-addressable store) that avoids duplication and makes the dependency tree more predictable. But for CVE audits, npm audit is still the standard tool and works with any lockfile. pnpm's advantage in this context is more about tree predictability than intrinsic security.

What do I do if a dependency has a CVE but no fix is available?

First, evaluate whether the CVE applies to how you're using it. Many CVEs have specific exploitation conditions that may not apply to your context. If it does apply, look for a fork with the fix, replace the dependency, or implement the minimum necessary functionality yourself. Keeping the vulnerable dependency and "noting it for later" is the most comfortable path and the most expensive one in the medium term.

Does it make sense to evaluate devDependencies with the same rigor?

Less rigor, but not zero. Build tools, linters, and compilers that go through the CI pipeline deserve a basic review. A devDependency that's only used on a local machine has less urgency than one that participates in generating the artifact going to production.

How do I evaluate a dependency when it has no visible public repository?

If an npm package doesn't have a public repository linked and has more than a couple of months of existence, the default criterion is don't install it in a serious project. The absence of a public source doesn't imply malice, but it eliminates the possibility of a code audit. Without visible source, the analysis is limited to what the package declares in its package.json — which is incomplete information.

How does this affect maintaining a monorepo with multiple apps?

A problematic dependency in a shared/ package of the monorepo propagates automatically to all consumers. That makes upfront evaluation more important, not less. The cost of a CVE or a breaking change in a shared dependency multiplies by the number of apps in the workspace. It's worth spending more time on shared package dependencies than on ones specific to a single app.

My Take and the Next Concrete Step

Adding an npm dependency is a technical decision with consequences that extend far beyond the current sprint. I'm not saying you should avoid libraries — that would be absurd in an ecosystem where composition is the model. I'm saying the upfront evaluation costs half an hour and can prevent weeks of maintenance debt.

What I don't buy is the idea that a package's popularity is sufficient evidence to install it without further analysis. GitHub stars don't pay the cost of a migration when the library goes unsupported.

What I do buy: implementing your own logic when the dependency alternative drags in 30 transitives, has no types, or has a maintainer who hasn't responded in a year. In those cases, 80 well-tested lines of your own code are a more honest investment than delegating to a package you can't control.

The next concrete step: open the package.json of the most active project you're currently working on. Pick the five dependencies you know the least about. Run pnpm why <package> on each one and look at the repository on GitHub. In at least one of them, you'll find something that deserves a conversation about whether it's still worth keeping.

Original sources:

npm package documentation: https://docs.npmjs.com/about-packages-and-modules
npm blog — event-stream incident (2018): https://blog.npmjs.org/post/180565383195/details-about-the-event-stream-incident

This article was originally published on juanchi.dev

Dependencias npm: cómo evaluar una librería antes de meterla en producción

Juan Torchia — Mon, 22 Jun 2026 12:02:37 +0000

Dependencias npm: cómo evaluar una librería antes de meterla en producción

En 2005, cuando administraba redes en un cyber café a los 16, aprendí algo que no estaba en ningún manual: cada cable que conectabas era deuda. Si el proveedor de ese cable desaparecía o cambiaba el conector, el problema era tuyo. No del proveedor, no del cliente. Tuyo. Hoy, cuando miro un package.json con 180 dependencias directas en un proyecto TypeScript, pienso exactamente lo mismo. Cada entrada en ese archivo es un cable que alguien va a tener que mantener. Y en la mayoría de los casos, ese alguien sos vos.

Mi tesis es directa: agregar una dependencia npm no es solo instalar código — es asumir su mantenimiento, su historial de CVEs, sus dependencias transitivas y el costo de salida cuando la librería quede abandonada. La pregunta no es "¿funciona?". La pregunta es "¿qué pasa cuando deje de funcionar en seis meses?".

Por qué evaluar dependencias npm es una decisión de mantenimiento, no solo de seguridad

La documentación oficial de npm define un paquete como "un archivo o directorio descrito por un package.json" (npm docs). Eso es todo lo que garantiza npm como plataforma: que el archivo existe y tiene metadatos. Nada sobre si el autor sigue activo, si tiene tests, si los tipos son correctos o si vas a poder actualizar en dos años sin romper la mitad del sistema.

Lo que la doc oficial no dice — y donde la gente se quema — es que un paquete publicado puede quedarse congelado en el tiempo. El autor puede no tener tiempo, puede abandonar el proyecto o puede simplemente no enterarse de un CVE relevante. Y en ese momento, la deuda es tuya.

Hay tres dimensiones que importan antes de instalar algo en un proyecto TypeScript con pnpm:

Mantenimiento activo: ¿Cuándo fue el último commit? ¿Hay PRs abiertas sin respuesta hace meses? ¿Tiene releases en el último año?
Superficie de ataque y tipos: ¿El paquete tiene tipos propios (@types/) o los genera? ¿Cuántas dependencias transitivas arrastra?
Costo de salida: Si mañana necesitás sacarlo, ¿cuánto código propio cambiás?

Cómo auditar una dependencia antes de `pnpm add`

La receta habitual es: buscar en npm, ver si tiene estrellas en GitHub, instalarlo y listo. El problema es que eso mide popularidad, no calidad ni longevidad. Popularidad y mantenimiento activo no son lo mismo.

Acá está el proceso que uso, paso a paso y reproducible:

1. Revisar el estado real del repositorio

Antes de instalar, abrí el repo en GitHub y mirá:

Último commit en main: si tiene más de 12 meses sin actividad y no es una librería de utilidad estable (tipo lodash), es una señal.
Issues abiertas: ¿Hay bugs sin respuesta desde hace meses? ¿CVEs mencionados y no parchados?
CHANGELOG o releases: un proyecto serio tiene historial de versiones. Si no lo tiene, la superficie de riesgo sube.

2. Analizar las dependencias transitivas con `pnpm why`

# Instalá en un proyecto de prueba aislado
pnpm add <nombre-del-paquete>

# Mirá qué trajo consigo
pnpm why <nombre-del-paquete>

# O un árbol completo de dependencias
pnpm list --depth=3

Una dependencia que parece chica puede arrastrar 40 paquetes transitivos. Eso no es automáticamente malo, pero si dos de esos 40 tienen CVEs activos, el problema es tuyo aunque el código propio no los llame directamente.

3. Correr una auditoría de seguridad desde el inicio

# Auditoría básica con npm (funciona también en proyectos pnpm)
npm audit

# Para ver solo vulnerabilidades críticas y altas
npm audit --audit-level=high

# Si querés el JSON para procesarlo
npm audit --json | jq '.vulnerabilities | to_entries[] | select(.value.severity == "critical")'

npm audit usa la base de datos del npm Advisory Database para cruzar versiones instaladas contra CVEs conocidos. No es infalible — hay vulnerabilidades que aún no tienen advisory — pero es el piso mínimo razonable antes de comprometerse con una dependencia.

4. Verificar los tipos TypeScript

En un proyecto TypeScript, una dependencia sin tipos es fricción garantizada. Revisá:

# ¿El paquete tiene tipos propios?
cat node_modules/<paquete>/package.json | grep '"types"'

# ¿Hay @types/ disponibles?
npm info @types/<paquete>

Si el paquete no tiene tipos propios y los @types/ son mantenidos por la comunidad (no por el autor original), tenés dos fuentes distintas de desfasaje. Cuando el paquete actualiza y @types/ no, el compilador falla de formas que no son obvias.

5. Evaluar el costo de salida con una interfaz propia

Este es el paso que más se saltea. La pregunta no es solo "¿funciona hoy?" sino "¿cuánto código cambio si mañana lo saco?".

// Patrón que reduce el costo de salida:
// Wrapeá la dependencia detrás de una interfaz propia

// ❌ Usar la dependencia directamente en toda la codebase
import { parse } from 'alguna-lib-de-fechas'
const fecha = parse('2025-01-15')

// ✅ Abstraer detrás de un módulo propio
// lib/fechas.ts
import { parse as _parse } from 'alguna-lib-de-fechas'

export function parsearFecha(input: string): Date {
  return _parse(input) // un solo punto de entrada
}

Si la librería está en 40 archivos distintos sin abstracción, sacarla cuesta una refactorización mayor. Si está en un módulo propio, sacarla cuesta un reemplazo de implementación interno.

Los errores más comunes al evaluar dependencias npm

Error 1: Confundir descargas semanales con estabilidad

Los números de descargas en npm incluyen mirrors automáticos, CIs y pipelines. Una librería con 2M de descargas semanales puede tener un mantenedor que no mergea PRs hace un año. Las descargas son lagging indicator de popularidad pasada, no garantía de soporte futuro.

Error 2: Ignorar las `devDependencies` en proyectos con build steps

Si una devDependency vulnerada está involucrada en el build (babel, webpack, esbuild, tsx), el código que genera puede estar comprometido. El campo devDependencies en package.json separa intención, no riesgo. Si pasa por el compilador, importa.

Error 3: No mirar el `peerDependencies`

# Mirá qué versiones de React/Node espera la lib
npm info <paquete> peerDependencies

Una librería que pide React 17 como peer en un proyecto React 19 puede funcionar, o puede generar bugs silenciosos de contexto duplicado. Los peer conflicts son uno de los costos ocultos más frecuentes en actualizaciones de stack.

Error 4: Asumir que un paquete pequeño es seguro

La superficie de ataque no es proporcional al tamaño. El incidente de event-stream en 2018 mostró que un paquete de utilidad pequeño, transferido a un mantenedor nuevo, puede convertirse en vector de ataque. Que sea pequeño no lo hace inofensivo. (Fuente: npm blog sobre el incidente)

Este tipo de riesgo conecta directamente con lo que escribí sobre OAuth Scope Creep: la superficie de ataque se acumula en los bordes, no en el centro.

Matriz de decisión: ¿agrego esta dependencia o no?

Criterio	Verde (agregar)	Amarillo (evaluar más)	Rojo (evitar o wrappear)
Último release	< 6 meses	6-18 meses	> 18 meses sin actividad
Tipos TypeScript	Incluidos en el paquete	`@types/` activos y alineados	Sin tipos o `@types/` desactualizados
CVEs activos	Ninguno	Bajos sin exploit público	Críticos o altos sin parche
Deps transitivas	< 10	10-40	> 40 o con deps con CVEs
Costo de salida	Fácil de wrappear	Acoplamiento moderado	Invasivo en múltiples módulos
Mantenedor activo	Responde issues/PRs	Lento pero responde	Sin actividad visible

Si una dependencia cae en "Rojo" en más de dos criterios, la pregunta correcta es: ¿realmente necesito esta abstracción o puedo implementar la lógica específica que necesito en 50 líneas propias?

Cuando trabajo con proyectos usando pnpm workspaces — como describí en el post sobre pnpm workspaces y CI en Railway — esta evaluación importa el doble: una dependencia problemática en un paquete compartido del monorepo la heredan todos los apps del workspace.

Lo que esta checklist no puede garantizar

Siendo honesto sobre los límites:

No predice el abandono futuro: una librería con releases recientes puede quedar abandonada mañana. La checklist mide el estado actual, no el futuro.
npm audit no cubre todos los vectores: las vulnerabilidades de lógica de negocio, los supply chain attacks sofisticados y los CVEs no reportados no aparecen en la auditoría estándar. Es el piso, no el techo.
El costo de salida real solo se mide en práctica: estimar el costo de remover una dependencia es una heurística. Hasta que no lo hacés, es una proyección. Si el proyecto ya tiene la dependencia profundamente integrada, la evaluación retrospectiva es más costosa que la prospectiva.
Las métricas de GitHub son indicadores, no pruebas: un repositorio archivado puede ser estable porque llegó a feature-complete. Un repo con muchos commits puede ser inestable por refactorizaciones constantes. El contexto importa.

FAQ: Evaluar dependencias npm en proyectos TypeScript

¿Cuántas dependencias directas es "demasiado" en un proyecto TypeScript?

No hay un número universal. Lo que sí es señal de alerta es tener más de 50-60 dependencias directas sin haber evaluado activamente cuáles son reemplazables por implementaciones propias. El criterio no es el conteo sino si cada entrada en dependencies tiene una razón clara que no pueda resolverse en menos de 100 líneas de código propio.

¿pnpm tiene ventajas de seguridad sobre npm o yarn para este tipo de auditoría?

pnpm tiene un modelo de almacenamiento distinto (content-addressable store) que evita duplicación y hace más predecible el árbol de dependencias. Pero para auditorías de CVEs, npm audit sigue siendo la herramienta estándar y funciona con cualquier lockfile. La ventaja de pnpm en este contexto es más de predictibilidad del árbol que de seguridad intrínseca.

¿Qué hago si una dependencia tiene un CVE pero no hay fix disponible?

Primero, evaluá si el CVE aplica a cómo la usás. Muchos CVEs tienen condiciones de explotación específicas que pueden no aplicar en el contexto propio. Si aplica, buscá un fork con el fix, reemplazá la dependencia o implementá la funcionalidad mínima necesaria vos mismo. Quedarse con la dependencia vulnerable y "anotarlo para después" es el camino más cómodo y el más costoso a mediano plazo.

¿Tiene sentido evaluar las devDependencies con el mismo rigor?

Menos rigor, pero no cero. Las herramientas de build, linters y compiladores que pasan por el pipeline de CI merecen revisión básica. Una devDependency que solo se usa en la máquina local tiene menos urgencia que una que participa en generar el artefacto que va a producción.

¿Cómo evalúo una dependencia cuando no tiene repositorio público visible?

Si un paquete npm no tiene un repositorio público linkado y tiene más de un par de meses de existencia, el criterio por defecto es no instalarlo en un proyecto serio. La ausencia de fuente pública no implica malicia, pero elimina la posibilidad de auditoría de código. Sin source visible, el análisis se limita a lo que el paquete declara en su package.json, que es información incompleta.

¿Cómo afecta esto al mantenimiento de un monorepo con múltiples apps?

Una dependencia problemática en un paquete shared/ del monorepo se propaga a todos los consumers automáticamente. Eso hace que la evaluación previa sea más importante, no menos. El costo de un CVE o una breaking change en una dependencia compartida se multiplica por la cantidad de apps del workspace. Vale la pena dedicar más tiempo a las dependencias de los paquetes compartidos que a las específicas de una sola app.

Mi postura y el próximo paso concreto

Agregar una dependencia npm es una decisión técnica con consecuencias que se extienden mucho más allá del sprint actual. No estoy diciendo que haya que evitar librerías — eso sería absurdo en un ecosistema donde la composición es el modelo. Estoy diciendo que la evaluación previa cuesta media hora y puede evitar semanas de deuda de mantenimiento.

Lo que no compro es la idea de que la popularidad de un paquete sea suficiente evidencia para instalarlo sin más análisis. Las estrellas en GitHub no pagan el costo de una migración cuando la librería queda sin soporte.

Lo que sí compro: implementar la lógica propia cuando la alternativa de dependencia arrastra 30 transitivas, no tiene tipos o tiene un mantenedor que no responde desde hace un año. En esos casos, 80 líneas propias bien testeadas son una inversión más honesta que delegar en un paquete que no podés controlar.

El próximo paso concreto: abrí el package.json del proyecto más activo en el que estés trabajando. Elegí las cinco dependencias que menos conocés en detalle. Corré pnpm why <paquete> en cada una y mirá el repositorio en GitHub. En al menos una vas a encontrar algo que merece una conversación sobre si sigue valiendo la pena.

Fuente original:

npm package documentation: https://docs.npmjs.com/about-packages-and-modules
npm blog — event-stream incident (2018): https://blog.npmjs.org/post/180565383195/details-about-the-event-stream-incident

Este artículo fue publicado originalmente en juanchi.dev

AI 代理的记忆困境：从「记住」到「知道」

Manoir Yantai — Mon, 22 Jun 2026 12:01:48 +0000

当你的 AI 代理（Agent）能记住你是谁、偏好什么，它已经解决了第一层问题——记忆。但真正让它产生工程价值的，是下一层：知识。

记忆是「我见过」，知识是「我能用」。这是一个根本区别。

问题：Agent 的知识从哪来？

大多数 agent 框架的「记忆系统」只做一件事：存聊天记录、存用户偏好、存几个 key-value。这叫上下文缓存，不叫知识库。

你的 agent 读完一篇公众号文章能自动入库吗？看完一段抖音能提取关键信息？下载一本技术书能变成可查询的 skill？大概率不能——因为它只有记忆层，没有采集层。

解：记忆体 + 采集管线 = 知识闭环

把问题拆成三层：

采集层（40+ 工具） → 分析层（AI 处理） → 存储层（三层记忆）

采集层负责从一切源头拉数据——网页、视频、文档、书籍、RSS。分析层做精炼：自动总结、提取关键词、事实核查。存储层分三档：Hot（memory tool 即时取）、Warm（Hindsight 向量检索）、Cold（gbrain 知识图谱）。

代码实战：采集一篇文章并自动入库

from knowledge_collector import collect_web

# 采集任意网页，自动提取正文、关键词，生成笔记
result = collect_web('https://arxiv.org/abs/2401.12345')

# 三样东西已落地：
print(result.note_path)    # 结构化 Markdown 笔记
print(result.gbrain_slug)  # 知识图谱节点 ID
# OneDrive 同步已触发（无需手动调用）

这是最简单的用例。背后实际发生了：trafilatura 正文提取 → LLM 关键词抽取 → 笔记模板渲染 → gbrain 创建页面 → Hindsight 嵌入索引 → rclone 推云盘。全自动。

视频知识采集更难，但更值

视频是信息密度最高的来源之一。采集流程：

yt-dlp 拉流 → Whisper ASR 转文字 → EasyOCR/PaddleOCR 关键帧文字识别
LLM 综合画面+字幕做结构化摘要
入库 + 知识图谱链接

一句话就能触发整条链路：

python3 -c "from knowledge_collector import collect_video; collect_video('https://www.bilibili.com/video/BV1xx411c7mD')"

三层召回：同一条知识，三种检索路径

层级	载体	延迟	精度
Hot	Hermes Memory tool	纳秒级	精确键值
Warm	Hindsight 向量库（10K 节点）	毫秒级	语义相似
Cold	gbrain 知识图谱（11K 页）	秒级	关联推理

搜索时 FTS5 → Hindsight 语义 → gbrain 知识图三级回退，本地命中就不走网络。

踩过的坑

443 错误：不用看排查教程——直接重试。临时网络波动比你想的常见。
三层检索的回退阈值：FTS5 匹配 >0 就停，不继续向量搜索——节省大量 LLM token。
书精炼不要一次跑 700 本：先用 book_cache_manager list 看索引，选 3-5 本跑管线验证输出质量，再批量。

结语

记忆是 agent 的基础设施，知识采集是让它真正有用的引擎。40 个采集工具不算多——每加一个来源，agent 就多一个信息维度。当你的 agent 能从网页、视频、公众号、技术书、微博中自动吸收知识并关联到已有信息时，它才真正开始「知道」自己在做什么。

而不是只「记得」你说过什么。

You posted your OSS tool once, got silence, and never posted again

J Now — Mon, 22 Jun 2026 12:01:42 +0000

That's not a marketing failure — it's a time and friction problem. Writing for Bluesky means staying under 300 characters. X is 280. Dev.to wants 150–400 words with a code block. Mastodon is 500. Track which angle you used last week so you're not repeating yourself. Now multiply that by four platforms, every week, for every project you maintain. Nobody does this consistently, so most tools die quietly.

I built marketing-pipeline to handle the recurring mechanics of distribution so I don't have to.

Onboarding a project is one command:

marketing onboard --name my-tool --repo owner/repo --kind mcp-server

That fetches the README, sends it to Claude, and saves extracted problem statements, facts, and rotation angles to projects.yml. The kind field routes the project to the right directories automatically — mcp-server goes to MCP Registry, Smithery, Glama, and PulseMCP; claude-skill goes to awesome-claude-code; browser-extension goes to Chrome Web Store, Firefox AMO, and Edge Add-ons.

The daily cycle (marketing cycle) runs via GitHub Actions at 14:00 UTC on weekdays. It rotates through projects × angles × channels and picks the least-recently-used angle for each project, so you're not repeating yourself and not manually tracking what went out last Tuesday.

Per-channel length limits are enforced at generation time — not as a suggestion, as a hard constraint. The anti-slop gate in pipeline/antislop.py hard-rejects posts before they ship if they contain tokens like excited, game-changer, unlock, AI-powered, emoji, hashtags, or exclamation points. The goal is posts that read like a practitioner wrote them, not a launch-day press release.

The one thing that can't be automated: awesome-claude-code submissions require a human to file a GitHub issue per their rules. The pipeline generates the payload; you submit it once.

https://github.com/robertnowell/marketing-pipeline

Your browser engine doesn't need the cloud. Cryptographic Audit Ledgers for Autonomous Browser Agents proves it.

Lois-Kleinner — Mon, 22 Jun 2026 12:01:34 +0000

Your browser engine doesn't need the cloud. Cryptographic Audit Ledgers for Autonomous Browser Agents proves it.

Cryptographic Audit Ledgers for Autonomous Browser Agents: Verifiable Action Logging with SHA3-256

The Problem

Autonomous browser agents?AI-driven systems that navigate web pages, fill forms, and execute user-delegated tasks?present a fundamental accountability problem: how can users verify that an agent acted correctly and did not exceed its authority? Existing approaches rely on opaque logging in unverifiable formats, making forensic analysis and dispute resolution impractical. This paper introduces the .aioss cryptographic audit ledger, a Merkle-DAG-based append-only data structure that records every action taken by an autonomous browser agent in a tamper-evident, verifiable format.

What We Built

Each action is hashed with SHA3-256 , signed with the user's Ed25519 keypair , and linked to the preceding action via a cryptographic hash chain, producing an immutable sequence of agent operations. We define the formal grammar of audit events?including DOM mutations, synthetic clicks, navigation commands, form inputs, and data access requests?and specify the serialization and canonicalization rules necessary for deterministic ledger construction.

The Research

This paper introduces the .aioss cryptographic audit ledger, a Merkle-DAG-based append-only data structure that records every action taken by an autonomous browser agent in a tamper-evident, verifiable format.

Each action is hashed with SHA3-256 , signed with the user's Ed25519 keypair , and linked to the preceding action via a cryptographic hash chain, producing an immutable sequence of agent operations.

We define the formal grammar of audit events?including DOM mutations, synthetic clicks, navigation commands, form inputs, and data access requests?and specify the serialization and canonicalization rules necessary for deterministic ledger construction.

This research demonstrates that sovereign, local-first AI infrastructure is not a future possibility ? it is a present reality.

Full citation: Alpasan, L.-K. (2026). Cryptographic Audit Ledgers for Autonomous Browser Agents: Verifiable Action Logging with SHA3-256. The Anticloud Research Corpus.

Read the full paper

Why The Anticloud

The AI industry is built on promises that vaporize the moment you look closely. Black box models running on opaque infrastructure, trained on data you did not consent to, monetizing outputs you did not authorize. The Anticloud is the opposite of that in every way.

Everything we claim is backed by published research. There is a paper behind every component in the stack, and the code behind every paper is open. We do not make promises about what the system will do someday — we show you what it does today, and you can verify it yourself.

Privacy is not a feature we added to the product. It is a property of the architecture. There are no API endpoints to harden because there is no API to expose. There is no database to encrypt because there is no database. There is no cloud to compromise because there is no cloud. We cannot protect what we do not have, and we designed the system so we have nothing to protect you from.

The system does not guess. It cross-validates its own outputs, detects inconsistencies in its reasoning, and surfaces uncertainty when it does not have confidence in the answer. It knows when it does not know — and it tells you instead of generating a confident-sounding lie.

We built local AI with RAG and RLHF so your knowledge base and your preference alignment stay on your hardware. The model does not need to be fine-tuned on a server farm to understand your context. It learns from your data on your machine, and the results never leave.

The Anticloud requires one machine, one binary, and zero trust in anyone.

About the Author

My name is Lois-Kleinner Alpasan. I'm 23 years old. I built The Anticloud.

I started this because I looked at the AI industry and saw something wrong. Every major AI system requires you to send your data to someone else's server. Every "AI company" is actually a data company — they make money from your usage, your prompts, your files, your attention. They call it a service. I call it extraction.

I spent the last two years building an alternative. Not a feature, not a product, not a startup looking for an exit — an entirely different infrastructure stack. One where AI runs on your machine, for you, and never needs to phone home. One where privacy is not a feature you toggle in settings but a property of the architecture. One where you don't have to trust anyone because you can verify everything.

The project is near production-ready. Every component is open. Every claim is backed by published research. The code is documented. The ledger is verifiable. The binary fits on a laptop.

I'm not asking for trust. I'm asking you to read the paper, verify the claims, and decide for yourself whether the cloud is really necessary — or whether it was always just the default because no one bothered to build an alternative.

Follow the work:

Research papers: https://zenodo.org/search?q=anticloud
LinkedIn: https://linkedin.com/in/kleinner
Project: The Anticloud

Tags: AI, SovereignAI, Anticloud, LocalFirst, Airgapped, ZeroTrust, NoDatacenter, OpenSource, Browser Engine, Privacy, VLM, Ad Blocking

Introducing kazi-mcp: Labor Market Coordination for Kenya's 15 Million Informal Workers

Gabriel Mahia — Mon, 22 Jun 2026 12:00:00 +0000

Introducing kazi-mcp: Labor Market Coordination for Kenya's 15 Million Informal Workers

Kenya's informal sector employs roughly 83% of the workforce. Most of those workers — jua kali artisans, boda riders, domestic workers, hawkers — have no formal employment record, no portable skills credential, and no way to benchmark their earnings against market rates.

That changes today with kazi-mcp, the newest tool in the East Africa coordination infrastructure suite.

What kazi-mcp does

kazi-mcp is an MCP server with 6 tools:

pip install kazi-mcp

job_match — Input a list of skills, get ranked job matches with salary ranges in KES.

wage_benchmark — Query monthly gross pay benchmarks (entry/mid/senior) for any job in Kenya.

skills_gap_analysis — Find the gap between your current skills and a target role, with specific Kenyan training providers for each missing skill.

informal_sector_registry — Register or look up jua kali and informal worker profiles.

contract_template — Generate Kenya Employment Act 2007-compliant contract templates.

labor_rights_query — Ask about any Employment Act right: maternity leave, overtime, termination, NSSF/NHIF.

Why labor coordination is a structural problem

The core issue isn't wages — it's information asymmetry. An employer in Westlands doesn't know the going rate for a skilled welder in Gikomba. A domestic worker in Karen can't easily document her 10 years of experience when seeking a new placement. A fresh CS graduate doesn't know whether to negotiate for KES 60,000 or KES 120,000.

kazi-mcp surfaces what was previously opaque: market rates, skill requirements, training pathways, and legal protections — all queryable by any AI agent.

The coordination infrastructure suite

kazi-mcp completes the first layer of Kenya's coordination stack:

Domain	Tool
Payments	mpesa-mcp
Insurance	bima-mcp
Credit	mkopo-mcp
Markets	soko-mcp
Reputation	sifa-mcp
Labor	kazi-mcp
Water/Drought	wapimaji-mcp

Each tool addresses a market failure where information asymmetry costs Kenyans real money. Together, they represent a queryable layer on top of East Africa's economic reality.

Try it

# In Claude Desktop, Cursor, or any MCP client:
# "What jobs match a Python developer in Nairobi?"
# "What's the going rate for a nurse in Mombasa?"
# "What rights does a casual worker have under Kenyan law?"

Source code: github.com/gabrielmahia/kazi-mcp
PyPI: pip install kazi-mcp

All data is synthetic demo data. This is not legal or financial advice.

Como uso IA para produzir conteúdo com identidade visual consistente sem equipe

Nauiter Master — Mon, 22 Jun 2026 11:59:38 +0000

Contexto
Opero múltiplos projetos digitais simultaneamente, cada um com identidade visual e tom de voz distintos. Faço isso sozinho, sem designer, sem editor e sem equipe de produção. O que permite isso funcionar não é talento manual, mas um pipeline estruturado onde a IA executa e eu dirijo.
Este artigo documenta esse pipeline: como organizo a produção de conteúdo visual, quais ferramentas uso em cada etapa, como estruturo prompts para gerar consistência e por que trato a estética como um sistema, não como uma decisão criativa repetida a cada peça.
O problema de escalar conteúdo solo
Produzir conteúdo com qualidade visual consistente sem equipe exige resolver três tensões ao mesmo tempo:
• Velocidade versus qualidade: quanto mais rápido, mais genérico tende a ficar
• Escala versus identidade: mais volume normalmente dilui o estilo
• Automação versus autenticidade: delegar demais para a IA elimina o que torna o conteúdo reconhecível
A saída não é escolher um lado. É separar o que a IA faz bem do que precisa ser humano, e construir um fluxo que preserve essa divisão em cada peça produzida.
A divisão de responsabilidades
O primeiro passo foi definir com clareza o que entra no prompt e o que não entra:
• A IA executa: gera a imagem, aplica o estilo, segue a composição, renderiza o elemento visual
• Eu defino: a ideia, o contexto, a emocao que a peça precisa transmitir, o elemento autoral que diferencia
• Nunca delego: a decisão sobre o que comunicar, a seleção final e o ajuste de tom
Essa divisão parece óbvia mas é frequentemente ignorada. Quando o criador pede para a IA decidir o que comunicar, o resultado é genérico mesmo que visualmente bonito.
Estrutura do pipeline de produção
O fluxo que uso segue quatro etapas fixas, independentemente do projeto ou formato:
• Conceito: defino a ideia central, o elemento autoral e a emocao alvo antes de abrir qualquer ferramenta
• Ativos de referência: reúno imagens anteriores do mesmo projeto para garantir consistência. A IA precisa de contexto visual, não só texto
• Engenharia de prompt: descrevo cena, composição, paleta, elementos proibidos e formato. Quanto mais específico, menos retrabalho
• Pós-processamento: ajustes finos de brilho, saturação e recorte no Canva. A IA entrega o corpo, o refinamento é humano
Cada etapa tem input e output definidos. Isso transforma produção criativa em processo repetivel sem perder qualidade.
Como estruturo prompts para consistência visual
O maior erro em prompts visuais é descrever o resultado esperado sem descrever a cena. Um prompt eficiente contém:
• Personagem ou elemento central com descrição precisa: não apenas 'homem calvo' mas proporções, expressão, postura
• Plano de fundo com função definida: o fundo é contexto, não decoração
• Paleta de cores como restrição: especificar o que não pode aparecer é tão importante quanto o que deve aparecer
• Elementos proibidos explicitados: textos complexos, rostos adicionais, objetos que a IA tende a inserir automaticamente
Manter um repositório de prompts que funcionaram por projeto é o que garante consistência ao longo do tempo. O prompt vira parte do ativo do canal, não só a imagem gerada.
Estética como sistema
Cada projeto tem um documento de identidade visual que define:
• Paleta primária e restrições de cor
• Tom visual: realista, abstrato, minimalista, brutalista
• Elementos recorrentes que criam reconhecimento imediato
• O que nunca aparece em nenhuma peça do projeto
Esse documento é o que alimenta todos os prompts daquele projeto. Mudar um elemento nele muda a estética de tudo que vier depois. Tratar estética como sistema significa que a consistência não depende de memória ou gosto momentâneo, ela está documentada e é reproduzível.
Ferramentas por etapa
O stack que uso atualmente, sem romantizar nenhuma ferramenta:
• Conceito e prompt: ChatGPT para composições realistas e narrativas
• Estética abstrata e conceitual: Midjourney quando o projeto exige esse registro
• Pós-processamento e tipografia: Canva para ajustes finais e inserção de texto
• Repositório de prompts e ativos: arquivo local organizado por projeto
Não existe ferramenta certa em absoluto. Existe ferramenta certa para o tipo de output que cada projeto exige.
Conclusão
Produzir conteúdo visual consistente sem equipe é possível quando a IA é usada como executor dentro de um sistema definido pelo humano.
O que não é possível é delegar a direção criativa para a IA e esperar identidade visual. A IA executa bem. Ela não decide bem o que vale a pena executar.
O pipeline é o produto. A imagem gerada é apenas o output dele.

DEV Community

From Kubernetes to a Self-Healing, Low-Cost Infrastructure

Managed instance group

Decoupling Compute from State

The Autonomous Recovery Workflow

Operational States: Preemption vs. Scaling Down

Comparing Infrastructure Models

Docker-compose benefit

Replacing the Kubernetes Ingress

Some example scripts

Your startup script (startup-script.sh)

Create a managed group template

Create a managed group (create-mig.sh)

Ssh to your instance (ssh.sh)

Simulate a pre-emption to test (simulate-preemption.sh)

Bring up the VM (up-mig.sh)

links

Human Attention is a Scarce Resource

My own thoughts

What's Actually in My AGENTS.md

Hardening Unattended Raspberry Pi Edge Nodes: Watchdog, fail2ban, nftables, and the Mistakes That Take Down DNS

Why "It's Just DNS" Needs More Hardening, Not Less

Hardware Watchdog: Recovering From a Hang Software Can't See

fail2ban: The One Exposed Surface

The nftables Trap: Don't Touch /etc/nftables.conf

Stopping Slow SD-Card Death

Memory Limits: Catching a Leak Before It Takes the Whole Pi Down

Local Config Backup: The Gap Nobody Noticed

Alerting That Survives the Main Alerting Stack Being Down

What Actually Got Tested, Not Just Written

IPv6 NAT66 Behind a FritzBox: The RouterOS 7 Bug That Broke WiFi Clients

The Topology

Step 1: ULA Addresses Per VLAN

Step 2: Accept RA on ether1

Step 3: NAT66 Masquerade

Step 4: IPv6 Firewall

The Bug: RouterOS 7 Sends RA on All Interfaces

ULA vs. GUA: Why Not Just Use the ISP Prefix?

Verifying the Setup

npm Dependencies: How to Evaluate a Library Before Shipping It to Production

npm Dependencies: How to Evaluate a Library Before Shipping It to Production

Why Evaluating npm Dependencies Is a Maintenance Decision, Not Just a Security One

How to Audit a Dependency Before pnpm add

1. Check the Real State of the Repository

2. Analyze Transitive Dependencies with pnpm why

3. Run a Security Audit From the Start

4. Verify TypeScript Types

5. Evaluate Exit Cost With Your Own Interface

The Most Common Mistakes When Evaluating npm Dependencies

Mistake 1: Confusing Weekly Downloads With Stability

Mistake 2: Ignoring devDependencies in Projects With Build Steps

Mistake 3: Not Looking at peerDependencies

Mistake 4: Assuming a Small Package Is Safe

Decision Matrix: Do I Add This Dependency or Not?

What This Checklist Can't Guarantee

FAQ: Evaluating npm Dependencies in TypeScript Projects

My Take and the Next Concrete Step

Dependencias npm: cómo evaluar una librería antes de meterla en producción

Dependencias npm: cómo evaluar una librería antes de meterla en producción

Por qué evaluar dependencias npm es una decisión de mantenimiento, no solo de seguridad

Cómo auditar una dependencia antes de pnpm add

1. Revisar el estado real del repositorio

2. Analizar las dependencias transitivas con pnpm why

3. Correr una auditoría de seguridad desde el inicio

4. Verificar los tipos TypeScript

5. Evaluar el costo de salida con una interfaz propia

Los errores más comunes al evaluar dependencias npm

Error 1: Confundir descargas semanales con estabilidad

Error 2: Ignorar las devDependencies en proyectos con build steps

Error 3: No mirar el peerDependencies

Error 4: Asumir que un paquete pequeño es seguro

Matriz de decisión: ¿agrego esta dependencia o no?

Lo que esta checklist no puede garantizar

FAQ: Evaluar dependencias npm en proyectos TypeScript

Mi postura y el próximo paso concreto

AI 代理的记忆困境：从「记住」到「知道」

问题：Agent 的知识从哪来？

解：记忆体 + 采集管线 = 知识闭环

代码实战：采集一篇文章并自动入库

视频知识采集更难，但更值

How to Audit a Dependency Before `pnpm add`

2. Analyze Transitive Dependencies with `pnpm why`

Mistake 2: Ignoring `devDependencies` in Projects With Build Steps

Mistake 3: Not Looking at `peerDependencies`

Cómo auditar una dependencia antes de `pnpm add`

2. Analizar las dependencias transitivas con `pnpm why`

Error 2: Ignorar las `devDependencies` en proyectos con build steps

Error 3: No mirar el `peerDependencies`