So I connected Hermes Agent to a self-hosted Honcho instance.

This isn’t about giving an AI a giant transcript and hoping it finds the right paragraph. Honcho stores conversations, builds representations of users and agents, and retrieves relevant context later. Hermes then injects that context into a new conversation, or queries it through memory tools. What you get is closer to continuity than to storage.

It remembers that I build Rust products with Dioxus and Axum, that I prefer direct answers, and that a given project has its own deployment convention. Those facts stay useful long after the original conversation has disappeared into session history.

That’s the promise, anyway. Setting it up also taught me that an enabled memory provider isn’t necessarily a working one. Authentication breaks quietly, background processing dies without telling you, and a status command will happily print OK while the useful part does precisely nothing.

So here’s the setup, the architecture, and the traps I’d avoid the second time.

Why ordinary chat history isn’t enough#

A conversation has short-term memory by default. The model sees the messages in its current context window and refers back to them. That works fine until the conversation gets compacted, or I start a new session, or I switch from the desktop app to another interface. It also breaks down when the useful fact lives in a conversation from three weeks ago, or when the history is too large to inject without burying the current task.

Saving every transcript solves storage. It doesn’t solve recall.

An agent needs to answer two different questions:

1. What happened in that old conversation?
2. What from that conversation still matters now?

The first is search. The second takes judgment.

Hermes already has local memory files and searchable session history, and Honcho sits beside those rather than replacing them. It adds a longer-lived model of the user and the agent, plus semantic search and reasoning over past conversations.

I like that split. A small explicit memory file is still the right home for durable facts I want to control by hand. Session search is still what I reach for when I need the exact conversation where a decision got made. Honcho earns its place in the fuzzy middle: preferences, recurring patterns, shifting project context, and the facts that quietly became important without anyone bothering to promote them into a file.

What Honcho actually runs#

The self-hosted stack isn’t one magical memory container. The official Compose setup runs four services:

• api, which accepts peers, sessions, messages, and queries on port 8000
• deriver, the background worker that turns raw conversation into observations, summaries, and peer representations
• database, PostgreSQL with pgvector, holding durable state and embeddings
• redis, for caching and background coordination

The deriver matters more than it first appears. If the API is healthy but the deriver isn’t processing, your messages still get stored while the memory layer never becomes useful. Congratulations, you’ve built a very elaborate chat archive.

Honcho also needs an LLM provider and won’t start without one, since it uses models for extraction, summaries, dialectic queries, and memory consolidation. Worth being clear-eyed about what that means: self-hosting the database doesn’t keep all your conversation content on your machine. If Honcho calls a hosted model, the relevant content still leaves your server for inference.

Which gives you three useful deployment categories.

Managed Honcho#

The least work, since Plastic Labs runs both the service and the memory models. This is where I’d start if I only wanted to find out whether persistent memory improves my workflow.

Self-hosted storage, hosted inference#

The database, vectors, and memory state live on infrastructure I control, while Honcho still calls an external model provider for extraction and reasoning. This is the practical middle ground for most developers, and it’s what I run. You get control over the durable memory without standing up a local model server.

Fully local#

Honcho and the inference models both run on your own machines. Strongest privacy boundary, largest operational bill, paid in electricity, hardware, and evenings lost to model-server configuration. Pick it because the data genuinely requires it.

Starting Honcho with Docker#

The upstream repository ships the Compose setup:

git clone https://github.com/plastic-labs/honcho.git
cd honcho
cp .env.template .env
cp docker-compose.yml.example docker-compose.yml

Your .env needs credentials for whichever model provider Honcho will use. The current upstream default expects LLM_OPENAI_API_KEY with an OpenAI-compatible text and embedding model, and you can point the Deriver, Dialectic, Summary, and Dream features somewhere else through the *_MODEL_CONFIG__TRANSPORT, *_MODEL_CONFIG__MODEL, and base URL overrides. Check the current docs before copying model names out of an old tutorial, because this part moves quickly.

Then build and start it:

docker compose up -d --build

Don’t skip --build. The Compose file builds Honcho from source, so the first run takes a while.

Once it’s up, check the API and the background worker separately:

docker compose ps
curl http://localhost:8000/health
docker compose logs deriver --tail 20

Don’t stop at the health endpoint. The upstream docs say plainly that it “only confirms the process is running. It does not check database or LLM connectivity.” It also tells you nothing about whether migrations finished, whether embeddings work, or whether Hermes can authenticate.

All Compose ports bind to 127.0.0.1 by default, which is the right call. If Honcho only ever runs on the same machine as Hermes, leave it there. For a remote agent machine, put it behind HTTPS and authentication instead of hanging port 8000 out on the internet.

My own instance doesn’t run from that Compose file. It runs as a Coolify service behind HTTPS on a private domain, with the api and deriver containers on the ghcr.io/plastic-labs/honcho:latest image. That’s where the next section comes from: the moment you put Honcho behind a domain you have to turn authentication on, and that’s where things got interesting.

The authentication trap#

This was the annoying part, and it has three separate layers.

Authentication is off by default#

A fresh self-hosted Honcho ships with AUTH_USE_AUTH=false, so every request is accepted. Fine on localhost. Not fine the moment the API has a public hostname.

Turning it on takes two steps. First, generate the secret:

python scripts/generate_jwt_secret.py   # produces AUTH_JWT_SECRET

Set AUTH_USE_AUTH=true and that secret in .env, then mint a token the server will actually accept. Inside a running container:

docker exec <api-container> /app/.venv/bin/python \
  scripts/generate_jwt.py --admin --print-only

To revoke everything you’ve issued, rotate AUTH_JWT_SECRET and restart.

Cloud keys aren’t self-hosted keys#

Honcho Cloud API keys and self-hosted tokens are different animals. A managed key starts with hch-v2-. A self-hosted server with auth enabled wants a JWT signed with your AUTH_JWT_SECRET. Paste a cloud key from app.honcho.dev into a self-hosted config and you get:

{"detail": "Invalid JWT"}

It’ll never validate, no matter how many times you re-copy it.

Two upstream bugs in the token script#

Both of these cost me time, and neither one is documented.

The first: uv run doesn’t work inside the container. The obvious invocation fails.

$ docker exec <api-container> uv run python scripts/generate_jwt.py --admin
error: honcho-ai references a workspace ... not a workspace member

Call the virtualenv interpreter directly instead, at /app/.venv/bin/python.

The second one is nastier: the --expires flag mints tokens the server then rejects. It writes the JWT exp claim as an ISO 8601 string where the spec wants a numeric timestamp, so the server refuses its own freshly issued token.

401 Unauthorized
{"detail": "Invalid JWT"}

Note that the error text is identical to the wrong-key case, which is exactly what made it slow to diagnose. Mint without --expires, and rotate the secret when you want to revoke.

Verify the token server-side first#

Before touching any client config, prove the token works against the API on its own:

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://honcho.example.com/v3/workspaces/list

A 200 with a JSON page object means the credential is good. Anything else is a server or token problem, and no amount of client configuration will fix it. That one command separates “my token is wrong” from “my integration is wrong,” which are the two failures that look completely identical from inside a chat client.

Connecting Hermes Agent#

Hermes has a first-party Honcho memory provider, and the supported path is the CLI wizard:

hermes memory setup honcho

Drop the provider name if you’d rather have the picker. For a local instance, give it the server base URL:

http://localhost:8000

For a remote deployment, use its HTTPS base URL.

The /v3 distinction#

Hermes wants the server base URL. The Honcho Claude Code plugin wants the versioned API endpoint. Same server, two different strings:

Hermes:            https://honcho.example.com
Claude Code:       https://honcho.example.com/v3

That bit me while connecting the second client. Similar-looking settings aren’t interchangeable just because they eventually talk to the same API.

Then check what Hermes actually resolved:

hermes memory status

There’s no hermes honcho subcommand, in case you go looking for one. hermes memory takes setup, status, off, and reset, and status is where the provider, resolved host, workspace, peers, and connection result show up.

My starting shape:

workspace:          hermes
user peer:          hauke
AI peer:            hermes
session strategy:   per-directory
recall mode:        hybrid

Session strategy also accepts per-repo, per-session, and global. I use per-directory because it keeps a stable session mapping for work done from the same folder, which matches how I actually work: one project, one directory, one accumulating thread of context.

hybrid gives Hermes both automatic context injection and the explicit Honcho tools. That’s a sensible default for a personal agent, since you get useful standing context without needing the model to remember to search every time, and the tools are still there when a task needs deeper recall.

One warning about reading the output. A status command can end with OK while the connection detail printed just above it says Invalid JWT. Read the connection block, not the final line. That’s the whole difference between checking that configuration exists and checking that it works.

Memory gets built asynchronously#

Honcho won’t hand you a mature profile right after the first message. Hermes writes conversations asynchronously, Honcho’s deriver processes them in the background, and peer cards, conclusions, and summaries all need messages to observe first. A brand new system will connect perfectly and still return nothing useful.

That’s not a failure. It’s just empty.

The distinction I use:

• Connection failure: invalid token, unreachable endpoint, API error
• Processing failure: messages arrive, but the deriver or the model calls fail
• Fresh memory: connection works, there just isn’t enough history yet
• Working recall: a new session retrieves a fact from an older one

Only that last one proves the feature I care about. The best smoke test is deliberately boring:

1. Tell Hermes one harmless, specific preference.
2. End the session.
3. Start a fresh session.
4. Ask Hermes to retrieve it with honcho_search.

Don’t test with something that already lives in USER.md, MEMORY.md, a repo instruction file, or the current prompt, or you’ll get a correct answer for the wrong reason.

How Hermes uses the memory#

Hermes runs Honcho in three recall modes.

hybrid injects standing context automatically and hands the model the Honcho tools. It’s the default, and mine. Continuity without turning every message into a manual search.

context injects context but withholds the tools. Simpler and more predictable, at the cost of deeper on-demand recall mid-task.

tools injects nothing and lets the model call Honcho when it decides it needs memory. Keeps prompts lean and makes retrieval visible, but it leans on the agent noticing that history matters in the first place.

Hermes exposes four tools, and they do genuinely different jobs:

If I need the exact command we agreed on, that’s search. If I want a synthesis of a preference, honcho_context fits better. And if I need one stable fact available cheaply in every single conversation, it belongs in the profile or in an explicit memory file, not in a retrieval call.

Sharing one backend with Claude Code#

Yes, you can, and this turned out to be the most useful part of the whole setup.

Honcho ships a Claude Code plugin that talks to the same self-hosted backend. It inherits nothing from your Hermes configuration. It reads ~/.honcho/config.json, and the workspace and peer names are yours to pick:

{
  "apiKey": "<your self-hosted JWT>",
  "peerName": "hauke",              // shared user identity
  "hosts": {
    "claude_code": {
      "workspace": "hermes",        // NOT the default "claude_code"
      "aiPeer": "claude"
    }
  },
  "endpoint": {
    "baseUrl": "https://honcho.example.com/v3"
  },
  "sessionStrategy": "per-directory"
}

Two details do the real work here.

The workspace has to match, and the defaults won’t do it for you. The plugin defaults to a claude_code workspace, while Hermes writes to whatever you named during its setup. Leave both at their defaults and you end up with two perfectly healthy integrations that share absolutely nothing. I pointed Claude Code at the hermes workspace on purpose, and that single line is what makes the memory common.

Then there’s observationMode, which decides whether the agents stay distinct. The default, unified, pools observations together. Set it to directional and each AI peer keeps its own view of you, so Claude’s observations stay with Claude and Hermes’ stay with Hermes:

{ "observationMode": "directional" }

That produces the architecture I wanted:

                    ┌── Hermes AI peer
Hauke user peer ────┤
                    └── Claude AI peer

          inside one deliberate workspace

One shared user identity, a separate representation per agent. Common facts about me travel between them without pretending Hermes and Claude are the same thing.

Two smaller things, each of which cost me a restart. The plugin reads apiKey from the config file, and while HONCHO_API_KEY works too, changing it means restarting Claude Code. And the endpoint here needs the /v3 suffix that Hermes specifically doesn’t want.

One last thing: don’t claim two agents share memory until you’ve written a fact through one and read it back through the other. Matching JSON files aren’t a test.

What I’d do differently#

I’d verify the system in layers, instead of configuring the whole thing and then asking why it remembers nothing. My order now:

1. Start PostgreSQL, Redis, the API, and the deriver.
2. Check container health and deriver logs.
3. Verify the Honcho API locally over plain HTTP.
4. Add HTTPS and AUTH_USE_AUTH=true, but only if remote access is actually required.
5. Mint a token and prove it with curl against /v3/workspaces/list.
6. Only then configure Hermes with the server base URL.
7. Read the full connection block from hermes memory status.
8. Write one harmless test fact.
9. Retrieve it from a fresh session.
10. Add the second client, matching the workspace name deliberately.
11. Only then start tuning recall modes, reasoning depth, and observation mode.

This keeps each failure small. Every step I skipped on the first attempt is a step that later cost me an hour of guessing which layer was broken.

I’d also start with managed Honcho if I were evaluating the idea rather than the infrastructure. Self-hosting before proving the memory improves my work would be classic developer behavior: building a small distributed system to avoid filling out one signup form.

Is self-hosting worth it?#

For most people trying Hermes, not on day one.

Managed Honcho takes the API, database, vector extension, worker, model configuration, authentication, backups, and upgrades out of the experiment entirely. That’s a much cleaner way to answer the first question, which is simply whether long-term agent memory helps you at all.

Self-hosting starts making sense when:

• conversation history is sensitive
• you want control over retention and backups
• multiple agents should share one memory backend
• you already operate the infrastructure it needs
• you want to pick the inference provider
• the system has become valuable enough to own

That third one was my actual reason. Two agents, one memory, one identity.

The tradeoff is straightforward enough. I get control over durable memory, and I take on responsibility for keeping the memory pipeline alive.

That last word is the one that matters. Persistent AI memory isn’t a JSON file with better branding, it’s a pipeline: ingestion, storage, background extraction, embeddings, retrieval, context assembly, and model inference. Every stage fails independently, and most of them fail quietly.

But when it works, the agent stops feeling like a clever stranger I have to brief every morning. It remembers the kind of software I build, the conventions around my projects, and the way I like to work. Not perfectly, and not magically. Just enough that the next conversation starts somewhere better than zero.

That’s worth a little infrastructure.

Just maybe not before coffee.

References#

• Honcho source and self-hosting overview
• Official Honcho self-hosting guide
• Honcho integration guide for Hermes Agent
• Hermes Agent Honcho memory documentation

None of them can afford an SEO agency. None of them can afford much of my attention either.

SEO tools always lost me at the same point: a dashboard, a subscription, and a score that says my site is a 34 without telling me what to publish on Tuesday.

What finally stuck was a git repo.

The repo#

First, credit where it belongs: claude-code-seo is not my work. mxfschr distilled years of r/SEO advice, mostly u/WebLinkr’s, into a markdown knowledge base and nine slash commands for Claude Code. I just use it, and adapted a few edges for my setup.

The idea is simple and a little radical: SEO as something you execute, not something you read about.

/seo-analyze mydomain.com

That pulls 90 days of my Google Search Console data over MCP, works out the hardest keywords I already rank top-7 for, and hands me three to five topics that extend that authority. With slugs, titles, and an internal linking plan.

Notice what is missing: a domain rating. The bar for “can this page rank” is what my pages already proved, not what a third-party score guesses.

Two details made it stick where the dashboards did not.

It hands me a plan. /seo-analyze returns three to five candidates with titles, slugs, and internal-link wiring. /seo-next-content turns the one I approve into a publish-ready brief.

It is honest. When there are no quick wins, it prints “0 quick wins” instead of inventing some. When a ranking only exists in a country I do not sell to, it says so. And before a content brief may claim a product feature, /seo-product-facts reads the actual code and cites file and line. No invented features, which matters more than ever now that LLMs repeat whatever you publish.

Running it costs almost nothing. The GSC API is free, DataForSEO is prepaid pay-per-call, and my weekly runs land between zero and eighteen cents.

My cadence#

• Weekly: /seo-quick-wins, which finds pages at position 4 to 15 that need exactly one push.
• Per topic I green-light: /seo-next-content for a publish-ready brief.
• Every six weeks or so: /seo-analyze re-maps where the authority is now.

I also avoid touching the same page twice within seven days. Search Console needs time to register each change, and stacked edits make cause and effect unreadable.

What I keep outside the terminal#

The Search Console MCP stays because the commands need GSC data. URL submission is separate. For ordinary pages, I submit the sitemap and use Search Console’s URL Inspection tool to request indexing on the URLs that matter.

Google’s Indexing API only supports pages with JobPosting or livestream BroadcastEvent markup. It is not a general URL-push API for blog posts, so I do not keep a separate indexing MCP server in the config. The terminal analyzes; Search Console handles manual requests.

The checklist that is not in the repo#

The repo is Google-first, and that is correct: Search Console is where the feedback loop lives.

But my audience is developers, and developers increasingly ask ChatGPT or Claude before they ever type into Google. Those products use their own crawlers and external search partners, so Google cannot be my only indexing check.

1. Google Search Console. The baseline. Submit the sitemap, and for pages that matter, request indexing on the URL directly. Nothing new here.

2. Bing Webmaster Tools, with IndexNow. OpenAI says ChatGPT Search sometimes works with external search providers and lists Bing among them. OpenAI also runs OAI-SearchBot, so Bing is not the whole pipe. It still matters. Bing Webmaster Tools can import verified sites from GSC. Then set up IndexNow: it immediately notifies Bing and the other participating engines when a URL changes. This blog pings IndexNow on every deploy, straight from the GitHub Actions pipeline. Most developers never open Bing. That habit is now backwards.

3. Brave. Anthropic tells site owners that Claude web search uses search partners, and its government web-search connector explicitly calls the Brave Search API. That does not prove every commercial Claude search comes solely from Brave. It is enough for me to treat Brave’s independent index as another discovery surface. Submitting a URL takes a minute.

Ten minutes of submissions, total. If your users ask AI assistants before they search, those ten minutes might matter more than the difference between position 3 and 4 on Google.

Two more things I do that are less checklist and more habit:

Ship open source, and let the platforms rank for you. github.com, npmjs.com, crates.io, docs.rs: these are some of the strongest domains on the internet, and every real project you publish gets a page on them. Those pages rank for your product name and your problem space long before your own young domain does, they link back to you, and LLMs read and cite them constantly. This is not a link scheme, and it does not work as one. It works when the repo or crate is a real thing people star and use. But if you were going to open source it anyway, publish it properly: good README, clear problem statement, link to your site.

Show the workflow instead of describing it. For tutorials, I record step-by-step demos with Stepshots, which is my own project, so calibrate for bias. The reason it belongs in an SEO post: tutorial pages that show every click answer the “how do I actually do this” queries that assistants and searchers both reward, and readers stay long enough to finish them.

What to expect#

Indexing is admission, not ranking. Submitting a URL across these discovery surfaces gets you evaluated, nothing more.

The repo’s own expectation management is the most honest I have seen in SEO material: new pages index in one to two weeks, reach position 10 to 15 in four to eight weeks if the internal linking is actually executed, and get their real evaluation over about thirteen months of click data. The maintainer took a zero-authority domain to page one in its niche with this exact loop, and still writes “there is almost certainly still some dumb-ass shit in here” at the top of the README.

That sentence is why I trust the repo. SEO compounds slowly, and the only way to survive that is a loop that runs on real data and admits what it does not know.

If you know SEO better than I do, the maintainer explicitly asks you to tear the repo apart. Open an issue. I will keep running the loop in the meantime: publish into proven authority, push what is almost there, and let GSC tell me what actually worked.

That waiting is dumb, and there’s a fix for it. IndexNow lets you tell search engines “this URL changed, come look now” with a single HTTP POST. We added it to both SeggWat and infra.page and tied it to our deploy pipeline, so every release pings the search engines automatically. It took an afternoon. This post is the whole thing.

What IndexNow actually is, and isn’t#

IndexNow is a tiny open protocol. You POST a list of URLs to one endpoint, and it fans the submission out to every participating search engine: Bing, Yandex, Seznam, Naver. One request, everyone hears about it.

Be honest with yourself about the “everyone,” though: Google is not on that list. Google has its own opinions about crawl scheduling and ignores IndexNow. So this isn’t a Google play. It’s a “get indexed fast on the other half of search” play, which is still worth an afternoon if you’re a small product trying to show up anywhere at all.

There are two pieces to it:

1. Proof you own the domain. You serve a key at https://yoursite.com/{key}.txt that returns the key as plaintext. That’s how IndexNow knows you’re allowed to submit URLs for that host.
2. The submission itself. A POST with the list of URLs you want recrawled.

Most tutorials show you doing both by hand, once. We wanted it to be automatic and zero-maintenance. Here’s how each piece works.

Piece 1: serve the key file, don’t commit it#

The lazy way is to drop a static key.txt in your public/ folder and forget about it. Don’t. That puts your key in the repo, ships it to every environment including local dev, and means the file exists whether or not the feature is actually configured.

Instead, serve it from the app, gated on a secret. The route only exists when the key is set, and the route path is the key. The handler just echoes it back:

// Serve the IndexNow key file at /{key}.txt.
// The route is only registered when the key is configured, and its path
// literally is the key, so any request that reaches this handler returns
// that exact key as plaintext, which is all IndexNow wants.
pub async fn indexnow_key() -> Response {
    let state = app_state();
    match state.indexnow_key.as_deref() {
        Some(key) => (
            [(header::CONTENT_TYPE, "text/plain; charset=utf-8")],
            key.to_string(),
        )
            .into_response(),
        None => StatusCode::NOT_FOUND.into_response(),
    }
}

Wire it up conditionally. No key, no route:

// Registered only when INDEXNOW_KEY is set. The whole feature stays inert
// on dev and on self-hosted deployments that never configured it.
let router = if let Some(key) = state.indexnow_key.clone() {
    router.route(&format!("/{key}.txt"), get(indexnow_key))
} else {
    router
};

The key itself is just openssl rand -hex 16, loaded from an env var. The payoff is simple: the secret never touches the repo, the file only exists in production, and everywhere else the route 404s. Nothing to clean up, nothing to leak.

Piece 2: submit on deploy, not on build#

Now the submission. The instinct is to fire it during the build. Resist it. You have to submit after the new content is actually reachable. Otherwise you’re inviting crawlers to URLs that may still 404 because the deploy hasn’t swapped over yet.

So this runs as the last step of the deploy job, after the container is up. Here’s the real step from our pipeline, with comments left in:

- name: Submit URLs to IndexNow
  env:
    INDEXNOW_KEY: ${{ secrets.INDEXNOW_KEY }}
    SITE: ${{ vars.SITE_URL || 'https://infra.page' }}
  run: |
    if [ -z "$INDEXNOW_KEY" ]; then
      echo "INDEXNOW_KEY not set — skipping."
      exit 0
    fi

    # host with no scheme/path, for the payload
    HOST="${SITE#http://}"; HOST="${HOST#https://}"; HOST="${HOST%%/*}"

    # Wait until the NEW release is live and serving the key file.
    # This is the bit everyone forgets: during a rolling swap there's a
    # window where the old container still answers. Poll until the key
    # file comes back with the expected value before submitting anything.
    KEY_URL="$SITE/$INDEXNOW_KEY.txt"
    ready=
    for i in $(seq 1 30); do
      body=$(curl -fsS --max-time 10 "$KEY_URL" 2>/dev/null || true)
      if [ "$body" = "$INDEXNOW_KEY" ]; then ready=1; break; fi
      echo "Waiting for $KEY_URL (attempt $i/30)…"
      sleep 10
    done
    if [ -z "$ready" ]; then
      echo "::warning::Key file not reachable after 5min — skipping."
      exit 0
    fi

    # The URL list IS the sitemap. One source of truth, can't drift.
    urls=$(curl -fsS --max-time 30 "$SITE/sitemap.xml" | grep -oP '(?<=<loc>)[^<]+' || true)
    count=$(printf '%s\n' "$urls" | grep -c . || true)
    [ "$count" -eq 0 ] && { echo "::warning::Empty sitemap — skipping."; exit 0; }

    payload=$(printf '%s\n' "$urls" | jq -R . | jq -s \
      --arg host "$HOST" --arg key "$INDEXNOW_KEY" --arg loc "$KEY_URL" \
      '{host: $host, key: $key, keyLocation: $loc, urlList: .}')

    status=$(curl -s -o /tmp/resp.txt -w '%{http_code}' \
      -X POST 'https://api.indexnow.org/indexnow' \
      -H 'Content-Type: application/json; charset=utf-8' \
      --data "$payload" || echo "000")

    if [ "$status" -ge 200 ] && [ "$status" -lt 300 ]; then
      echo "✅ IndexNow accepted $count URLs (HTTP $status)."
    else
      echo "::warning::IndexNow returned HTTP $status. Deploy is unaffected."
    fi

A few details matter more than they look.

The poll loop is the big one. During a rolling deploy there’s a window where the old container is still answering requests. If you submit in that window, you might be telling crawlers about content that isn’t live yet, or the request goes to a box that’s about to die. So we poll the key file until the new release serves it. The key file does double duty here: it proves ownership and gives us a cheap “is the new version up?” check.

The sitemap is the URL list. We don’t hand-maintain a list of URLs to submit. We read sitemap.xml and pull every <loc>. Your sitemap already knows what’s indexable, so reusing it means the submission list can’t drift from reality. Add a page, it shows up in the sitemap, it gets submitted. No second list to forget about.

Best-effort, always. Every failure path is a ::warning:: and an exit 0. An SEO ping must never fail your deploy. By the time this step runs, your app is already live and serving users. If IndexNow is having a bad day, that’s IndexNow’s problem, not your release’s. Letting a search-engine nicety break a production deploy is exactly backwards.

The tradeoffs we made on purpose#

This is a deploy-time mechanism, so it has edges. Fine. Just know which ones you’re accepting:

• It fires on deploy, not on content change. For mostly-static sites like a marketing site, docs, or a blog, that’s perfect. Content changes are deploys. For infra.page, where users create public pages at runtime, those pages only get re-pinged on the next deploy. They’re still in the sitemap so they do get submitted, just not instantly. If you need instant pings for runtime content, fire one from your app when the content changes. The deploy step and a live ping can live together.
• Each deploy re-submits the whole sitemap. We don’t diff. IndexNow is fine with this, and “submit everything that’s indexable” beats maintaining a changed-since-last-time list. If your sitemap grows into the thousands and this starts to feel rude, that’s when you add a diff. Not before.
• It’s bash in CI, not code in the app. On purpose. The trigger is deterministic, it’s visible in the workflow log, it’s re-runnable, and it submits only after the release is provably live. Doing it in-app means wiring it into your boot sequence and reasoning about which instance submits. For deploy-time submission, the CI step is the simpler, more honest place for it.

That last point is also why the same pattern dropped cleanly into two different products with one decision flipped per product: SeggWat scopes submission to our own first-party marketing and docs pages, while infra.page lets the sitemap include public user pages too. Same machinery, different sitemap.xml. The pattern doesn’t care what’s in the list.

Did it work?#

Generate your key, set INDEXNOW_KEY as a CI secret (and in your runtime env so the app serves the file), deploy, and then check Bing Webmaster Tools → IndexNow. It shows submission counts and any rejected URLs. If the key file isn’t reachable it’ll tell you there, which is a much nicer feedback loop than guessing.

Worth it?#

This is the kind of infra chore that pays rent quietly. It cost an afternoon, it costs nothing to run, and now every release tells half the search world to come look, without anyone remembering to do it. For a small team shipping a product nobody’s heard of yet, “get found faster, for free, forever” is an easy yes.

The whole thing is maybe sixty lines split across a Rust handler and a CI step. If you’ve got a sitemap and a deploy pipeline, you already have the hard parts. Go connect them.

Sending "hello" over a socket is easy. Maintaining a growing pile of loosely shaped JSON messages across client code, server handlers, UI state, and tests is where the fun starts to rot.

That is why the WebSocket support in Dioxus 0.7 is interesting. Dioxus Fullstack builds on top of Axum’s WebSocket API, but adds the thing Rust developers usually want: shared types.

Instead of treating the socket as a string tunnel, you can model the messages flowing in both directions.

That sounds small. It is not.

It means your realtime feature can start with actual Rust types instead of “please remember this payload shape in three places”.

Why WebSockets?#

Most web apps can get pretty far with plain HTTP.

A form submit is fine when the user sends something once and waits for a result. A normal API call is fine when the UI needs to fetch a list, update a record, or save a setting.

WebSockets become useful when the connection itself matters.

Examples:

• a feedback widget receiving live replies
• a build log streaming output
• a multiplayer or collaborative UI
• progress updates for long-running jobs
• notifications that should arrive without polling
• a dashboard that reflects backend state quickly

You can fake some of this with polling. Sometimes polling is the right boring answer.

But once the client and server need to talk repeatedly, in order, over the same session, a WebSocket is the better primitive.

The Dioxus 0.7 shape#

Dioxus Fullstack provides WebSocket support that works alongside server functions.

The important pieces are:

• WebSocketOptions
• Websocket
• options.on_upgrade(...)
• typed input and output messages
• optional custom encoding

At the simplest level, a server function accepts WebSocketOptions and returns a Websocket.

The official Dioxus docs show the basic idea with an uppercase echo socket:

#[get("/api/uppercase_ws")]
async fn uppercase_ws(options: WebSocketOptions) -> Result<Websocket> {
    Ok(options.on_upgrade(move |mut socket| async move {
        // Send an initial greeting.
        _ = socket.send("Hello!".to_string()).await;

        // Echo messages back in uppercase.
        while let Ok(msg) = socket.recv().await {
            _ = socket.send(msg.to_ascii_uppercase()).await;
        }
    }))
}

That already gives you a useful realtime channel.

The server upgrades the HTTP request to a WebSocket connection, then keeps receiving and sending messages while the socket is alive.

Under the hood, Dioxus wraps Axum’s WebSocket upgrade flow. The nice part is that you do not have to drop out of the Dioxus Fullstack model just because one part of your app needs bidirectional communication.

The default Websocket type#

The Websocket type is generic over three parameters:

pub struct Websocket<In = String, Out = String, E = JsonEncoding> {
    // ...
}

Those parameters are:

1. the type received from the client
2. the type sent back to the client
3. the encoding used for messages

By default, both message directions use String, encoded as JSON.

That is fine for a toy echo example. It is less nice once your feature has real events.

For real app code, I usually want explicit event types.

Not because enums are fancy. Because debugging random string protocols at 1am is a self-inflicted wound.

Adding typed messages#

Let’s say the client sends text input and the server responds with the uppercase version.

We can model that as two enums:

use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, Debug)]
enum ClientEvent {
    TextInput(String),
}

#[derive(Serialize, Deserialize, Debug)]
enum ServerEvent {
    Uppercase(String),
}

Now the WebSocket function can return a typed socket:

#[get("/api/uppercase_ws")]
async fn uppercase_ws(
    options: WebSocketOptions,
) -> Result<Websocket<ClientEvent, ServerEvent>> {
    Ok(options.on_upgrade(move |mut socket| async move {
        while let Ok(event) = socket.recv().await {
            match event {
                ClientEvent::TextInput(text) => {
                    let response = ServerEvent::Uppercase(text.to_ascii_uppercase());
                    _ = socket.send(response).await;
                }
            }
        }
    }))
}

This is the part worth caring about.

The socket is no longer “some text comes in, some text goes out”.

It is:

ClientEvent -> ServerEvent

The compiler now knows what the protocol looks like.

If you add a new client event later, Rust can help you find the places that need to handle it. If the server sends a response variant the UI does not expect, that mismatch becomes visible in code instead of hiding in runtime behavior.

That is the boring magic of fullstack Rust.

A more realistic event shape#

The uppercase example is useful because it is tiny. But most actual realtime features are event streams.

For example, a feedback widget might send events like this:

#[derive(Serialize, Deserialize, Debug)]
enum ClientEvent {
    DraftChanged {
        text: String,
    },
    FeedbackSubmitted {
        page_url: String,
        message: String,
    },
}

And the server might respond with:

#[derive(Serialize, Deserialize, Debug)]
enum ServerEvent {
    Connected {
        session_id: String,
    },
    DraftAccepted,
    FeedbackReceived {
        id: String,
    },
    Error {
        message: String,
    },
}

That already reads like a small protocol.

And because it is plain Rust, you can keep it boring:

• simple enums
• simple structs
• no mystery strings
• no undocumented JSON blobs
• no “frontend knows this by convention” nonsense

This is the part where Dioxus starts to feel different from a typical frontend/backend split. The message contract can live close to both sides of the feature.

WebSockets are stateful#

There is one caveat you should not ignore: WebSockets are stateful.

A WebSocket connection ties a client and server together for a session. That is the point. It is also the cost.

This matters when deploying.

If your app runs in an environment where requests are short-lived, serverless, or aggressively moved around, you need to think carefully about where the connection lives and how session state is preserved.

For a normal long-running Axum-style service, this is usually fine.

For serverless environments with request time limits, it can get awkward quickly.

That is not a Dioxus problem. That is WebSockets being WebSockets.

Encoding choices#

Dioxus also lets you customize the encoding.

The default is JSON, which is the right choice when compatibility matters. If third-party clients might connect, JSON is boring and useful.

For Rust-only clients, binary encodings like CBOR or MsgPack can make more sense.

The type shape looks like this:

Websocket<ClientEvent, ServerEvent, CborEncoding>

I would not start there unless you have a reason.

JSON first. Optimize later. Future-you has enough problems.

Where this is actually useful#

Typed WebSockets are not something every app needs on day one.

But they become valuable the moment “submit and wait” stops being enough.

A few places where this pattern fits well:

Live feedback#

For a feedback product like SeggWat, WebSockets could support richer interactions than a plain form submit.

For example:

• user starts typing feedback
• widget validates or classifies input
• server sends acknowledgement
• dashboard receives the new feedback event
• support/admin UI updates without refresh

Not every feedback flow needs that. A calm form is often better than a hyperactive realtime UI.

But once feedback becomes part of a live product surface, the protocol matters.

Build logs and job progress#

If your app starts long-running jobs, WebSockets are a natural fit.

The client sends:

ClientEvent::StartJob { id }

The server streams:

ServerEvent::JobStarted
ServerEvent::LogLine(...)
ServerEvent::Progress(...)
ServerEvent::JobFinished

That is much cleaner than hammering /status every second and hoping the UI catches up.

Collaborative interfaces#

Anything collaborative eventually needs a shared event model.

Even if you do not build full Google Docs-style collaboration, small shared-state features benefit from typed messages:

• presence
• cursor position
• comments
• edit notifications
• shared dashboard updates

Again, the win is not that WebSockets exist. The win is that the messages are modeled directly.

Keep the protocol boring#

The biggest mistake with realtime features is getting clever too early.

A good WebSocket protocol should be almost dull.

Prefer this:

enum ClientEvent {
    MessageSent { text: String },
}

enum ServerEvent {
    MessageAccepted { id: String },
    MessageRejected { reason: String },
}

Over this:

struct SocketPayload {
    kind: String,
    data: serde_json::Value,
}

The second version feels flexible. It is also where type safety goes to die quietly behind the shed.

Use serde_json::Value at the edges if you must. Do not make it the center of your app protocol unless you enjoy writing bugs with both hands.

Practical gotchas#

A few things worth remembering:

Handle disconnects normally#

A WebSocket can close. The network can vanish. A laptop can sleep. A browser tab can disappear.

Design the server loop assuming recv() eventually fails.

while let Ok(event) = socket.recv().await {
    // handle event
}

When the loop ends, clean up anything tied to that connection.

Do not hide all errors#

The examples often use:

_ = socket.send(response).await;

That keeps the sample small. In production code, you may want to log send failures or break out of the loop when the connection is gone.

Avoid huge message types#

Typed does not mean enormous.

Keep messages focused. If one enum variant becomes half your app state, split the feature.

Think before using WebSockets on serverless#

WebSockets want a persistent connection. Some serverless platforms support that. Some make it painful. Some technically support it but make the architecture weird.

If the deployment target fights stateful connections, do not pretend it is fine. Pick SSE, polling, a queue, or different infrastructure.

Why I like this pattern#

The nice thing about Dioxus Fullstack is not that it removes the frontend/backend boundary completely.

It does not. The boundary is still there.

The nice thing is that the boundary can become typed.

That matters most in the small glue code where web apps usually get messy:

• request payloads
• response shapes
• socket messages
• form types
• route params
• optimistic UI state

WebSockets make that mess more visible because the communication is long-lived. If the protocol is vague, the feature gets vague too.

Dioxus gives you a way to keep it explicit.

Client sends ClientEvent.

Server sends ServerEvent.

Encoding is declared.

The connection upgrade is handled through the fullstack layer.

That is a nice default.

Final thought#

Typed WebSockets are not magic. You still have to handle deployment, disconnects, errors, and state.

But they remove one very annoying class of bugs: the kind where the frontend and backend silently disagree about what a message is supposed to look like.

For realtime features, that is a big deal.

And for fullstack Rust, it is exactly the kind of boring correctness that makes the stack worth using.

References#

• Dioxus 0.7 WebSockets documentation
• Dioxus Fullstack overview

You can ship the best feature in your niche and still lose someone who decided, with no evidence either way, that you’re a ghost town. That decision is the default. People assume abandonment unless you give them a reason not to.

Underneath it are two questions running in the back of every user’s head:

1. Is this thing actually working?
2. Does anyone here listen, and do they ship?

Most of us answer neither in public. The infra is fine — but only I can see the dashboard. I read every piece of feedback — but from the outside it looks like it falls into a void. The information that would answer both questions already exists. It’s just private.

I think of the fix as a trust layer: a small set of public-facing surfaces whose only job is to answer those two questions before anyone has to ask. And because I’d rather own my stack than rent it, I run that layer self-hosted. This post is how I wire it up.

Why self-hosted, specifically#

There’s a particular irony in renting your trust layer.

A status page hosted on someone else’s SaaS can go down when they go down — and now your “is it up?” page is part of the outage. A feedback board on a third-party platform means your users’ words, your roadmap, and your changelog live in someone else’s database, behind someone else’s export button, priced per seat.

For the surfaces whose entire point is trust, I want the opposite properties: I own the data, I control what’s public, and the thing runs on infrastructure I can see. That’s not ideology for its own sake — it’s just matching the tool to the job. A trust layer you don’t control isn’t fully a trust layer.

Both halves below are self-hosted, open-source, and ship as a single binary or a Docker image. I build most of my stack in Rust for exactly the reasons you’d guess: small footprint, boring reliability, runs happily on a cheap VM.

Surface 1: a status page you own#

When something feels slow or broken, a user has two options. Email you and wait. Or assume you’re down and walk.

A public status page gives them a third: check for themselves. It answers “is it just me?” at 3am on a Sunday without a support ticket, and it answers it the same whether you’re awake or not.

For a small product this doesn’t need to be a wall of green checkmarks maintained by an SRE team. It’s one public page showing what’s actually running: uptime, recent incidents, the services you depend on, maybe a couple of live metrics.

The one I run is infra.page — a self-hosted, open-source infrastructure dashboard. Think Linktree for your project’s infrastructure: it pulls the things you already operate (uptime monitors, GitHub, Sentry, analytics, and more) into drag-and-drop widgets on a single page. It has owner-vs-visitor visibility, so you decide exactly what the outside world sees versus what stays internal, you can point it at your own domain, and since it’s self-hosted the page isn’t coupled to a vendor that can fail alongside you.

A quick rule of thumb for what to expose:

• Public: uptime, current incidents, a short note after something breaks.
• Public if you can: a response-time or request-volume trend — a visible heartbeat is reassuring.
• Keep internal: anything that’s a security signal (exact topology, raw error detail, cost data).

The honesty test for an incident note: would you be comfortable if a user read it during the outage? If yes, publish. Owning a 20-minute blip in public buys more trust than pretending it never happened — they already noticed.

Surface 2: a feedback board you own#

The second question is the one I care about most, because feedback tools usually get it backwards.

You can collect feedback flawlessly and still look dead. If every request lands in a private inbox, the person who sent it has no idea whether it arrived, whether anyone agreed, or whether anything happened. From their seat it’s indistinguishable from piping to /dev/null.

The fix is to move the loop into the open. Three pieces that reinforce each other:

• A public feature-request board. Users post ideas, vote on each other’s, and watch status move from “under review” to “planned” to “shipped.” A vote count is a public promise that demand is real and that you can see it.
• A roadmap that’s just the board, sorted. You don’t need a second tool. “Here’s what’s planned, here’s what’s in progress” is the same board filtered by status. The point isn’t precision — nobody holds you to dates — it’s signal that someone’s steering.
• A public changelog. The closing half of every loop: someone asked, you built it, you say so. A steady “what’s new” stream is the most underrated trust signal a small product has, because it can’t be faked — you either ship or you don’t.

The feedback half I run is SeggWat, which is also self-hosted-friendly and gives you the board, the roadmap, and the changelog out of one widget. Its changelog can pull straight from GitHub releases and completed requests, so keeping it current isn’t another chore competing with actual work.

The magic is the handoff between the three: a request comes in → collects votes → moves to “planned” → ships → shows up in the changelog → the person who asked sees their idea become a line item. That visible arc is what turns a passive user into someone who recommends you.

The two surfaces are one promise#

Here’s why I bundle them instead of treating them as unrelated tools.

A status page says: the machine is running.
A feedback board and changelog say: the people are running it.

Users need both. A product that’s always up but never changes feels abandoned. A product that ships constantly but keeps falling over feels reckless. Show both, in public, and you’ve answered the only two trust questions that matter — before anyone had to email to ask.

And neither asks you to manufacture anything. The infra is already up; the status page just points at it. You already read feedback and ship; the board and changelog just turn that outward. The trust layer isn’t extra work. It’s the work you already do, made visible.

A small starting point#

You don’t need all of this on day one. The minimum viable trust layer is two links in your footer, both pointed at things already true about your product:

• Status → a self-hosted dashboard like infra.page wired to your uptime monitor.
• Roadmap / Changelog → a feedback board like SeggWat so users can ask, vote, and see what shipped.

Two links. Owned, not rented. You’re not promising transparency in a blog post nobody reads — you’re just no longer hiding the parts that build trust.

Show people the machine is running. Show them someone’s home. Then get back to building.

I built one into SeggWat, a feedback widget for websites. Here’s what it does, how it works, and why I think MCP is becoming table stakes for dev tools.

The real problem with feedback tools#

Collection is solved. Nobody actually consumes the result.

The pattern I see all the time:

1. A team installs a feedback widget.
2. Users submit bug reports, feature ideas, and ratings.
3. Feedback piles up in a dashboard nobody opens.
4. Product decisions get made on gut feel anyway.

Dashboards make you go and look. Email digests get filtered. Slack notifications turn into noise. The signal is there, no one is in the chair.

So I started asking a different question: what if the feedback data was available wherever I’m already working, including inside my AI coding assistant?

What MCP actually is#

The Model Context Protocol is an open protocol from Anthropic. A standard way for any LLM to ask structured questions to your application. Think of it as the REST API for AI workflows: instead of your own code asking questions you anticipated, any AI can ask anything and the protocol negotiates the right tool calls.

Before:

Me: “What are users complaining about?”
AI: “I don’t have access to your feedback data.”

With MCP:

Me: “What are users complaining about?”
AI: calls list_feedback → “47 submissions this week. Top issues: mobile login timeout (12), dark mode contrast in settings (8), broken Stripe redirect (3)…”

Now the AI is actually useful for the question you wanted to ask.

How SeggWat’s MCP server works#

The server lives at https://seggwat.com/mcp. It uses streamable HTTP transport: clients POST JSON-RPC, the server replies (and streams) via Server-Sent Events. Auth is your project’s API key, passed either as Authorization: Bearer <key> or X-API-Key: <key>. Every session is scoped to a single project. No cross-tenant data leakage.

The flow:

Client (Claude Desktop, Cursor, etc.)
  → POST /mcp
  → JSON-RPC tool call
  → API-key auth + project scoping
  → MongoDB query
  → Structured JSON back
  → AI interprets and presents

The tools#

The current tool surface:

• list_projects: projects under your API key.
• list_feedback, get_feedback: query and read feedback with filters for status, type, search, and page.
• create_feedback, update_feedback, delete_feedback: full lifecycle. The AI can triage, change status, write resolution notes, soft-delete.
• list_ratings, get_rating: query helpful, star, and NPS ratings.
• create_rating, create_typed_rating, delete_rating: write ratings of all three types.
• get_rating_stats, get_typed_rating_stats: aggregates including helpful percentages, star distributions, and NPS with promoter / passive / detractor breakdown.

Every tool returns structured JSON the AI can compare and reason about.

Use cases I actually run#

Morning standup context. I ask “summarize feedback from the last 24 hours, flag anything critical” and get a prioritized briefing in chat instead of opening a dashboard.

Sprint planning. “What are the top requested feature ideas this month? Group by theme.” The AI clusters by topic and gives me a ranked list, no manual sorting in a UI.

Release validation. The widget tags submissions with your app version via the data-version attribute, so I can ask “compare feedback between v2.3 and v2.4, did the new onboarding reduce complaints?” and get a real diff, not a feeling.

Automated triage. Pair the MCP server with a coding agent. After deploy: “any new feedback mentioning errors since 14:30 UTC? If critical, open a GitHub issue.” That closes the loop between deploy, feedback, and action without anyone watching a dashboard.

Customer success. “Show me all 1-star and 2-star ratings this week, draft personalized follow-ups.” The AI already has the page, version, and message, so the replies reference the actual issue.

Why not just use the REST API?#

You can. SeggWat has one. The difference is intent.

A REST API answers questions your code anticipated. An MCP server answers questions someone thinks up on the spot. With REST you build integrations: GET /feedback?status=new&limit=10. With MCP you say “what’s going wrong?” and the model picks the right tools and combines the results.

That gap gets bigger every month.

The Rust side#

The dashboard is Rust on Axum. The MCP server runs in the same process, using the rmcp crate for transport. Tools are async methods on a SeggwatTools struct, annotated with #[tool(description = "...")], and the macro generates the JSON schema, so request validation happens at compile time. Serialization is serde. No runtime surprises.

Lessons from building it:

• Tool names and descriptions are not decoration. list_feedback works, query confuses the model into pseudo-SQL. Be specific.
• Keep responses structured but readable. Add computed fields like days_since_submission so the AI can reason temporally without a date library.
• Per-project auth, not god-mode keys. MCP sessions are long-lived, and one over-permissioned key is a long-running blast radius.
• Rate-limit like the REST API. A single prompt can fire three to five tool calls, and a curious AI can hammer your database without one.

Where this is going#

The SaaS tools that survive the next few years will be the ones natively accessible to AI workflows. “Add a chatbot” is the bare minimum. Actually being AI-native looks like:

• Exposing your data via MCP so any assistant can query it.
• Accepting structured input so agents can take real actions.
• Emitting events so workflows can react in real time.

A feedback tool that only works through a web dashboard loses to one that works inside the IDE, the CI pipeline, the Slack channel, and the AI assistant you already have open.

SeggWat’s MCP server is a bet on that. It’s already how a lot of our more technical users interact with their feedback.

Try it#

1. Sign up at seggwat.com.
2. Drop one script tag on your site.
3. Generate an API key in Settings → API.
4. Point your MCP client at https://seggwat.com/mcp with that key.
5. Ask questions.

EU-hosted, GDPR-friendly, screenshot annotation, ideas portal, and an MCP server. $6/month, 14-day free trial.

Originally published on the SeggWat blog.

What is the SEN5x?#

The SEN5x is Sensirion’s environmental sensor node series. Depending on the variant, you get different measurement capabilities:

The SEN55 is the most capable model, giving you a full picture of indoor air quality from a single sensor. All variants communicate over I2C at address 0x69.

The Driver#

The sen5x crate provides a complete, type-safe interface for all three sensor variants. It’s built on embedded-hal 1.0, works in no_std environments, and comes with full async support via embedded-hal-async.

Add it to your project:

[dependencies]
sen5x = "0.2"

# For async support (e.g., with Embassy)
# sen5x = { version = "0.2", features = ["embedded-hal-async"] }

Features#

• Blocking and async APIs — full feature parity between Sen5x and Sen5xAsync
• no_std by default — runs on bare-metal microcontrollers without heap allocation
• CRC validation — every I2C read is verified using Sensirion’s CRC8 checksum
• defmt support — opt-in embedded logging with the defmt feature
• Command safety — the driver tracks measurement state internally and prevents invalid command sequences

Getting Started#

Here’s a minimal example reading air quality data on a Raspberry Pi using linux-embedded-hal:

use linux_embedded_hal::{Delay, I2cdev};
use sen5x::Sen5x;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let i2c = I2cdev::new("/dev/i2c-1")?;
    let mut sensor = Sen5x::new(i2c, Delay);

    // Reset and give the sensor time to boot
    sensor.device_reset()?;
    Delay.delay_ms(200);

    // Print device info
    let name = sensor.product_name()?;
    let serial = sensor.serial_number()?;
    let version = sensor.version()?;

    println!("Product: {}", core::str::from_utf8(&name).unwrap().trim_end_matches('\0'));
    println!("Serial:  {}", core::str::from_utf8(&serial).unwrap().trim_end_matches('\0'));
    println!("Firmware: {}.{}", version.firmware_major, version.firmware_minor);

    // Start measuring
    sensor.start_measurement()?;

    loop {
        Delay.delay_ms(1000);

        if sensor.data_ready()? {
            let data = sensor.measurement()?;
            println!(
                "PM2.5: {:.1} µg/m³ | Temp: {:.1} °C | Humidity: {:.1} % | VOC: {:.0} | NOx: {:.0}",
                data.mass_concentration_pm2p5,
                data.ambient_temperature,
                data.ambient_humidity,
                data.voc_index,
                data.nox_index,
            );
        }
    }
}

The sensor updates every second. After calling start_measurement(), poll data_ready() and read with measurement() when new data is available.

Async on Embedded — ESP32-C3 with Embassy#

For microcontroller targets, the async driver is the way to go. Here’s how it looks on an ESP32-C3 using Embassy:

use embassy_time::{Duration, Timer};
use sen5x::Sen5xAsync;

#[embassy_executor::task]
async fn air_quality_task(i2c: I2c<'static, Async>) {
    let mut sensor = Sen5xAsync::new(i2c, embassy_time::Delay);

    sensor.device_reset().await.unwrap();
    Timer::after_millis(200).await;

    sensor.start_measurement().await.unwrap();

    loop {
        Timer::after(Duration::from_secs(1)).await;

        if sensor.data_ready().await.unwrap() {
            let data = sensor.measurement().await.unwrap();
            defmt::info!(
                "PM2.5: {} | Temp: {} | VOC: {}",
                data.mass_concentration_pm2p5,
                data.ambient_temperature,
                data.voc_index,
            );
        }
    }
}

The API is identical to the blocking version — just add .await. No separate learning curve.

Beyond Basic Measurements#

The driver exposes the full SEN5x feature set, not just the basics:

Fan management — trigger manual cleaning cycles or configure the auto-cleaning interval:

sensor.start_fan_cleaning()?;
// or
sensor.set_fan_auto_cleaning_interval(604800)?; // weekly

Temperature compensation — correct for self-heating or enclosure effects:

sensor.set_temperature_offset_simple(2.5)?; // offset in °C

VOC/NOx algorithm tuning — adjust the on-chip gas index algorithm parameters for your specific environment.

Algorithm state backup — save and restore the VOC algorithm state across power cycles. This avoids the 12-hour learning phase after every reboot:

let state = sensor.voc_algorithm_state()?;
// persist `state` to flash/EEPROM
// ... after reboot:
sensor.set_voc_algorithm_state(state)?;

Error Handling#

Errors are generic over the underlying I2C implementation, keeping the driver platform-agnostic:

pub enum Error<E> {
    I2c(E),       // Underlying bus error
    Crc,          // Data integrity failure
    NotAllowed,   // Command invalid in current state
    Internal,     // Sensor reported a fault
}

Enable the thiserror feature for std::error::Error integration, or defmt for embedded-friendly formatting.

Links#

• Crate: crates.io/crates/sen5x
• Source: github.com/hauju/sen5x-rs
• Docs: docs.rs/sen5x
• Datasheet: Sensirion SEN5x Datasheet

Now there’s a better way. Sentry’s new CLI and MCP server let AI coding agents like Claude Code query your Sentry data directly from the terminal. No tab switching. No copy-pasting. Just ask “what’s breaking in production?” and get answers with full stack traces, right where you write code.

Here’s how to set it up and use it.

What Changed: The New Sentry CLI#

Sentry now has two CLIs. The legacy sentry-cli is the build tool you know — it handles source maps, releases, and debug symbols in CI/CD pipelines. That one stays.

The new sentry CLI is different. It’s an interactive developer tool built for both humans and AI agents. It can list issues, inspect events, query the API, and even call Sentry’s AI (Seer) for root cause analysis — all from your terminal.

The key distinction: the new CLI is designed to be used by your coding agent as much as by you.

Installation#

Install the new CLI:

curl https://cli.sentry.dev/install -fsS | bash

Or if you prefer a package manager:

# bun
bun add -g sentry

# npm
npm install -g sentry

Then authenticate:

sentry auth login

This opens a browser for OAuth. Once you authorize, credentials are stored in ~/.sentry/config.json. Every agent tool that wraps this CLI inherits your auth — no extra tokens to manage.

Verify it works:

sentry auth status

Option 1: Register as a Claude Code Skill#

The fastest way to give Claude Code access to Sentry:

npx skills add https://cli.sentry.dev

That’s it. Claude Code can now:

• List and inspect Sentry issues
• View full error events with stack traces
• Browse your projects and organizations
• Execute arbitrary Sentry API calls

This approach uses the CLI under the hood, so it inherits whatever authentication you’ve already set up.

Option 2: Sentry MCP Server (More Power)#

For deeper integration, Sentry offers a full MCP (Model Context Protocol) server with 16+ tools. This gives agents structured access to more of Sentry’s capabilities.

Remote Mode (Easiest)#

No installation needed. Add this to your Claude Code MCP config:

{
  "mcpServers": {
    "sentry": {
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

On first connection, you authenticate via OAuth in your browser. The server is always up to date since Sentry hosts it.

Local Stdio Mode (Self-Hosted / Offline)#

If you run a self-hosted Sentry instance or need local control:

{
  "mcpServers": {
    "sentry": {
      "command": "npx",
      "args": ["@sentry/mcp-server"],
      "env": {
        "SENTRY_ACCESS_TOKEN": "your-sentry-user-auth-token"
      }
    }
  }
}

For self-hosted deployments, add --host=sentry.example.com to the args.

Your token needs these scopes: org:read, project:read, project:write, team:read, team:write, event:write.

Claude Code Plugin#

You can also install it as a Claude Code plugin:

claude plugin marketplace add getsentry/sentry-mcp
claude plugin install sentry-mcp@sentry-mcp

Real Debugging Workflows#

Here’s where it gets practical. Once your agent has access to Sentry, you can debug production errors without leaving your editor.

“What’s broken right now?”#

Just ask:

“Show me the latest unresolved issues in my project”

The agent queries Sentry, returns a list of issues with titles, frequency, and first/last seen timestamps. No browser needed.

Investigate a Specific Error#

“What’s the full stack trace for PROJ-1234?”

The agent pulls the latest event for that issue, showing the complete stack trace, breadcrumbs, tags, and context. You’re looking at the same data you’d see in Sentry’s web UI, but right in your terminal alongside your code.

AI-Powered Root Cause Analysis#

This is the killer feature. Sentry’s Seer AI can analyze issues deeply:

# From the CLI directly
sentry issue explain PROJ-1234

# Or ask your agent
> "Use Sentry's Seer to analyze issue PROJ-1234 and suggest a fix"

Seer doesn’t just show you the stack trace — it analyzes the error pattern, identifies the likely root cause, and generates a step-by-step fix plan. When invoked through your coding agent, it can even propose code changes in context.

Cross-Reference Errors with Your Code#

“Check Sentry for errors in src/api/auth.ts and propose fixes”

The agent searches for Sentry issues related to that file, pulls the relevant stack traces, and suggests fixes based on both the error data and your actual source code. This is the workflow that used to take 20 minutes of tab-switching, now handled in a single prompt.

Monitor in Real-Time#

The new CLI supports log streaming:

sentry log list -f

The -f flag works like tail -f — it streams new log entries as they arrive. Useful during deployments or when you’re trying to reproduce an issue.

Tips for Effective Agentic Debugging#

Be specific with project names. If you have multiple projects, include the project name or slug in your prompt. The CLI auto-detects from your codebase when possible, but being explicit avoids ambiguity.

Use JSON output for scripting. Every CLI command supports --json:

sentry issue list --json | jq '.[0].title'

Combine with your existing tools. Pipe Sentry data to jq, fzf, or any other CLI tool. The structured output is designed for composition.

Let the agent fix, not just find. The real power isn’t just seeing errors — it’s having the agent read the stack trace, find the relevant code, and propose a fix in one flow. Don’t stop at “show me the error.”

MCP vs CLI Skills vs Seer — When to Use What#

You don’t have to choose just one. The CLI skill is great for quick lookups, while the MCP server gives agents deeper access for complex investigations. Seer is the specialist you call in when you need AI to analyze the why behind an error.

What This Changes#

The traditional debugging loop — see alert, open Sentry, read stack trace, switch to IDE, find file, understand context, write fix — collapses into a single conversation with your coding agent.

You say “there’s a TypeError in production, fix it” and the agent:

1. Queries Sentry for the issue
2. Reads the full stack trace and breadcrumbs
3. Opens the relevant file in your codebase
4. Understands the context around the failing code
5. Proposes (or writes) a fix

That’s the promise of agentic debugging. And with Sentry’s CLI and MCP server, it actually works today.

Get started: cli.sentry.dev | MCP Server: docs.sentry.io/product/sentry-mcp

Every developer has done it. You clone a repo, copy .env.example to .env, fill in your secrets, and get to work. Maybe you’ve even accidentally committed that .env file once. GitHub helpfully reminds you that you just published your database credentials to the world.

But here’s the thing most teams haven’t caught up with yet: your codebase is no longer just read by humans and CI pipelines.

AI coding assistants — Claude Code, GitHub Copilot, Cursor, Cody — now read your entire repository as context. Every file. Every config. Every .env.local that “shouldn’t be there but works fine for now.”

The new threat model#

When you use an AI coding tool, it typically ingests:

• Your entire project structure
• Configuration files
• Environment files if they exist in the repo
• Docker compose files with hardcoded credentials
• Any file that isn’t in .gitignore — and sometimes even those

This isn’t a vulnerability in the AI tools. It’s the whole point: they need context to help you code. But if your secrets live in your repo as plain text files, they become part of that context. They get sent to APIs. They appear in autocomplete suggestions. They end up in log files.

The .env file was designed for a world where only your local machine read your code. That world is gone.

What we do instead: justfile + Infisical#

We use a combination of just (a modern command runner) and Infisical (an open-source secrets manager) to keep secrets out of the repository entirely.

Here’s what a typical justfile looks like:

init:
    infisical run -- docker compose up -d

serve:
    infisical run -- cargo run

test:
    infisical run -- cargo test

migrate:
    infisical run -- npx prisma migrate dev

Notice infisical run -- before every command that needs environment variables. That prefix pulls secrets from Infisical’s vault, injects them as environment variables for that process only, and never writes them to disk.

No .env file. No secrets in the repo. No secrets in your shell history. No secrets for AI tools to accidentally ingest.

Why justfile over Makefile or npm scripts?#

just is a command runner, not a build system. The distinction matters:

1. It does one thing well. No implicit rules, no dependency graphs, no tab-vs-space wars. You write commands. You run them.

2. It works with any language. Your monorepo has Python, TypeScript, Go, and a docs site? just doesn’t care. It runs shell commands.

3. The syntax is readable. Compare:

# Makefile: Is this a build target or a command? Who knows.
serve:
    infisical run -- npm run dev
.PHONY: serve

# justfile: It's a command. Obviously.
serve:
    infisical run -- npm run dev

4. It lists available commands. Running just --list gives you a summary of every task. New team member? They run just --list and immediately know what’s available.

5. It supports arguments and defaults. Need to run migrations against different databases?

migrate env="development":
    infisical run --env={{env}} -- npx prisma migrate deploy

Now just migrate targets development, and just migrate staging targets staging. Try doing that cleanly in a Makefile.

Why Infisical (or any secrets manager) over .env files?#

The .env pattern has three fundamental problems:

Problem 1: .env files multiply#

It starts with one .env. Then you need .env.local, .env.development, .env.production, .env.test, .env.staging. Then someone adds .env.example that’s always out of date. Then someone adds secrets.json for a different service.

With Infisical, you have one source of truth with environments (dev, staging, prod) built in. You switch environments, not files.

Problem 2: .env files are unshareable#

New developer joins the team. “Hey, can someone send me the .env file?” Now your secrets are in Slack DMs, email threads, and shared Google Docs. Each copy is a potential leak.

With Infisical, new developers run infisical login, select their project, and they’re ready. Secrets are scoped by role — the intern doesn’t get production database credentials.

Problem 3: .env files have no audit trail#

Who changed the API key? When? Why? With .env files, you’ll never know. Someone overwrites it, someone copies the wrong value, and three hours later you’re debugging a production issue because staging credentials ended up in prod.

Infisical provides version history, access logs, and change tracking for every secret.

The AI angle is real, not hypothetical#

Consider what happens with a typical AI-assisted workflow:

1. Developer has .env with DB_URL=mongodb://root:p4ssw0rd@prod-server:27017/
2. Developer asks Claude Code: “Help me debug the database connection”
3. The AI reads the project context, including .env
4. The secret is now in the API request to the AI provider

With infisical run --, that .env file doesn’t exist. The AI sees a clean justfile with infisical run -- prefixes. It understands the pattern. It can help you debug without ever seeing your actual credentials.

Your secrets stay where they belong: in the vault, not in context windows.

Setting it up: 15 lines to a secure workflow#

1. Install just and Infisical#

# macOS
brew install just infisical/get-cli/infisical

# Linux
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash
curl -1sLf 'https://dl.cloudsmith.io/public/infisical/infisical-cli/setup.deb.sh' | sudo bash
sudo apt-get install infisical

2. Login and initialize#

infisical login
infisical init    # Links your repo to an Infisical project

3. Create your justfile#

# Start all services
init:
    infisical run -- docker compose up -d

# Run your app
serve:
    infisical run -- npm run dev

# Run tests
test:
    infisical run -- npm test

# Run with a specific environment
serve-staging:
    infisical run --env=staging -- npm run dev

4. Add .env to .gitignore (if you haven’t already)#

.env
**/*.env
secrets.json

That’s it. From now on, just serve handles everything.

The team workflow#

Here’s what the daily workflow looks like:

• Morning: just init to start services, just serve to run the app. No copying files, no asking teammates for secrets.
• New feature needs a new secret: Add it in Infisical’s dashboard. Team gets it automatically next time they run any just command.
• New team member: infisical login, just serve. Done.
• AI pair programming: Ask Claude Code anything. It sees your justfile, understands the pattern, and helps you without ever accessing your secrets.

Common objections#

“But Infisical adds a network dependency.” True. If Infisical is down, infisical run fails. For CI/CD, you can use Infisical’s service tokens with caching. For local dev, the CLI caches secrets locally (encrypted). It’s not a hard dependency for offline work.

“My team is small, .env files are fine.” Today. But when you add your first AI coding tool — and you will — your threat surface changes overnight. Setting this up takes less time than recovering from a leaked secret.

“Can I use something other than Infisical?” Absolutely. The pattern works with any secrets manager:

# Infisical
serve:
    infisical run -- npm run dev

# Doppler
serve:
    doppler run -- npm run dev

# 1Password CLI
serve:
    op run -- npm run dev

# AWS Secrets Manager (via chamber)
serve:
    chamber exec production -- npm run dev

The tool doesn’t matter. The pattern does: secrets injected at runtime, never stored in files.

The bottom line#

The combination of justfile + a secrets manager gives you:

• Zero secrets in your repo for AI tools (or anyone else) to find
• One command to run anything: just serve, just test, just deploy
• Consistent environments across the team without manual file copying
• Audit trails for who accessed which secrets and when
• Language-agnostic task running that works for any project in your monorepo

Your .env file was a good idea in 2015. In 2025, with AI reading every file in your project, it’s a liability. Replace it with a pattern that was built for how we actually work now.

The Old Way#

await page.click(‘#submit-btn-v2-new’);
await page.waitForSelector(‘.modal-content > div:nth-child(3) > button’);

Selectors break. Tests become maintenance nightmares.

The New Way#

Write test cases that read like requirements:

TEST-ONBOARD-001: New User Redirect

Priority: Critical
Preconditions: User with no organizations

Steps:
1. Create test scenario with user having no orgs
2. Login as that user
3. Navigate to /dashboard
4. Verify redirect to /onboarding
5. Verify plan selection cards displayed

Expected Results:
- Users without orgs redirected to onboarding
- Plan cards show Starter and Pro options

Hand this to agent-browser. It navigates, clicks, validates. Done.

Why This Matters

• Tests read like specs. PMs understand them. No translation layer.

• Resilience to UI changes. Button renamed? Class refactored? AI adapts.

• Faster authoring. Describe the flow, run it, ship it.

You spend time debugging an obscure error. The AI figures it out. Session ends. Next time you hit the same issue? Start from scratch.

This is one of the biggest inefficiencies in AI-assisted development today.

A new open-source Claude Code skill offers a solution: persistent learning across sessions.

How it works:

When Claude Code discovers something non-obvious during a coding session—a debugging technique, a workaround, a project-specific pattern—it automatically saves that
knowledge as a reusable skill.

Next time a similar problem comes up, the skill loads automatically. No re-learning required.

The research behind it:

This isn’t just a clever hack. It’s grounded in academic work on skill libraries for AI agents:

• Voyager (2023): Showed game-playing agents can build reusable skill libraries over time
• CASCADE (2024): Introduced “meta-skills”—skills for acquiring skills
• Reflexion (2023): Demonstrated that self-reflection improves agent performance

The insight: Agents that persist what they learn outperform agents that start fresh every time.

Why this matters for developers:

We’re moving from AI tools that assist to AI agents that learn. The difference is compounding value—every debugging session makes future sessions faster.

This is early, but it points to where AI development tools are heading: knowledge that accumulates, not knowledge that resets.

Check out the project: https://github.com/blader/claude-code-continuous-learning-skill

The Problem with AI-Assisted Development#

When working with AI assistants, you often find yourself in these situations:

• The AI is making changes to your codebase while you want to continue working
• You need to test AI-generated code without risking your current work
• Multiple AI sessions are working on different features simultaneously
• You want to compare AI implementations against your own

Traditionally, you’d either wait, stash your changes, or juggle multiple clones of your repository. All of these options are painful.

Enter Git Worktree#

Git worktree lets you check out multiple branches of the same repository into different directories simultaneously. Each worktree shares the same .git directory, so they’re all connected.

# Create a new worktree for AI work
git worktree add ../my-project-ai-feature feature-branch

# Now you have:
# /my-project          <- your main working directory
# /my-project-ai-feature <- AI assistant's playground

Why This Is Perfect for AI Coding#

1. Parallel Workflows#

Point your AI assistant at the worktree directory while you continue working in the main directory. No more waiting. No conflicts.

# Terminal 1: You working in main
cd my-project
vim src/important-file.ts

# Terminal 2: AI assistant working in worktree
cd my-project-ai-feature
claude-code "implement the new auth system"

2. Safe Experimentation#

AI assistants can make sweeping changes. With worktrees, those changes are isolated. If the AI creates a mess, you simply:

git worktree remove ../my-project-ai-feature

Your main directory remains untouched.

3. Easy Comparison#

Want to see what the AI did vs. your approach? Both directories exist simultaneously:

diff -r my-project/src my-project-ai-feature/src

Or open both in your IDE side-by-side.

4. Multiple AI Agents#

Running multiple AI sessions on different tasks? Create multiple worktrees:

git worktree add ../project-auth auth-feature
git worktree add ../project-api api-refactor
git worktree add ../project-tests test-coverage

Each AI agent works independently without stepping on each other.

5. Shared Git History#

Unlike separate clones, worktrees share the git database. Commits made in any worktree are immediately visible to all others. Merging AI work back into main is seamless.

Practical Workflow#

Here’s a typical workflow I use:

# 1. Create a feature branch and worktree for AI
git checkout -b feature/ai-implementation
git worktree add ../project-ai feature/ai-implementation

# 2. Point AI assistant at the worktree
cd ../project-ai
# Start AI coding session here

# 3. Continue your own work in main
cd ../my-project
git checkout main
# Work normally

# 4. Review AI changes
cd ../project-ai
git diff main
# Run tests, review code

# 5. Merge when satisfied
cd ../my-project
git merge feature/ai-implementation

# 6. Clean up
git worktree remove ../project-ai
git branch -d feature/ai-implementation

Tips and Tricks#

List all worktrees:

git worktree list

Prune stale worktrees:

git worktree prune

Lock a worktree to prevent accidental deletion:

git worktree lock ../project-ai

The Bottom Line#

Git worktree transforms how you can work with AI coding assistants. Instead of a sequential, blocking workflow, you get parallel, isolated development environments that share the same repository.

The AI can experiment freely. You can work uninterrupted. And when it’s time to integrate, everything is already in the same git repo.

If you’re serious about AI-assisted development, git worktree isn’t just nice to have—it’s essential.

Start small: next time you’re about to let an AI assistant make changes, create a worktree first. You’ll wonder how you ever worked without it.

I needed a lightweight way to collect feedback without adding comment sections or analytics bloat. That’s when I built SeggWat’s embeddable widgets and integrated them into this blog.

Here’s exactly how I did it.

The Problem with Traditional Feedback#

Most developer blogs either have no feedback mechanism or rely on:

• Comments — Great for discussions, but noisy and require moderation
• Contact forms — High friction, most readers won’t bother
• Analytics — Tells you what people read, not if it helped

I wanted something simpler: a quick way for readers to say “this helped” or “I found an issue” without leaving the page.

The Solution: Two Widgets#

SeggWat provides two embeddable widgets that solve different problems:

1. Feedback Button — A floating button for detailed feedback (bug reports, suggestions, questions)
2. Helpful Rating — A simple thumbs up/down for “Was this page helpful?”

Both are vanilla JavaScript, load asynchronously, and require zero dependencies.

Step 1: Create a SeggWat Project#

First, I created a project in the SeggWat dashboard specifically for this blog. This keeps feedback organized and separate from other projects.

The dashboard gives you a unique project key—a UUID that identifies your project when feedback is submitted.

Step 2: Add the Feedback Button via Ghost Code Injection#

Ghost has a built-in Code Injection feature that makes this trivial. No theme editing required.

1. Log into Ghost admin at yourblog.com/ghost
2. Navigate to Settings → Code injection
3. Paste the script in Site Header:

<script defer
  src="https://seggwat.com/static/widgets/v1/seggwat-feedback.js"
  data-project-key="your-project-key-here"
  data-button-color="#3eb0ef"
  data-button-position="bottom-right"
  data-enable-screenshots="true">
</script>

4. Click Save

That’s it. A feedback button now appears on every page.

Configuration Options#

I customized a few things:

• data-button-color — Matches Ghost’s default accent blue (#3eb0ef)
• data-button-position — bottom-right keeps it out of the way but accessible
• data-enable-screenshots — Lets readers annotate screenshots when reporting bugs

Other positions available:

• right-side — Vertical button on the right edge
• icon-only — Compact round button (good for mobile-heavy sites)

Step 3: Add “Was This Helpful?” to Posts#

For the helpful rating widget, I wanted it inline at the bottom of each post rather than floating. Ghost’s theme templating makes this possible.

The data-show-comment-link="true" option shows a “Leave a comment” link after a negative rating, which opens the feedback modal for more context.

If you want the rating on every post automatically, modify your Ghost theme’s post.hbs:

{{!-- At the bottom of post.hbs, before closing </article> --}}
<div class="post-helpful-rating">
  <script
    src="https://seggwat.com/static/widgets/v1/seggwat-helpful.js"
    data-project-key="your-project-key-here"
    data-question="Was this post helpful?">
  </script>
</div>

Then upload the modified theme via Settings → Design → Change theme → Upload theme.

What I Learned from the Feedback#

After a few weeks of collecting feedback, patterns emerged:

1. Broken links were common — External links rot faster than expected
2. Code examples needed context — Readers wanted to know which versions of tools I was using
3. Some posts were genuinely helpful — The positive feedback on certain posts guided what to write next

The per-page helpful ratings showed which posts were actually useful vs. which ones were just getting traffic.

Technical Details#

Both widgets:

• Load asynchronously with defer (no render blocking)
• Auto-detect the page URL for context
• Support multiple languages (English, German, Swedish)
• Work on mobile with touch-optimized interfaces
• Require no cookies or tracking

The screenshot annotation feature uses SnapDOM for capturing and includes tools for arrows, rectangles, text, and redaction.

API for Power Users#

If you want to go further, SeggWat has a REST API for programmatic access:

# List all feedback for a project
curl -X GET "https://seggwat.com/api/v1/projects/YOUR_PROJECT_ID/feedback" \
  -H "X-API-Key: $SEGGWAT_API_KEY"

# Get rating statistics
curl -X GET "https://seggwat.com/api/v1/projects/YOUR_PROJECT_ID/ratings/stats" \
  -H "X-API-Key: $SEGGWAT_API_KEY"

I use this to pull weekly summaries into my workflow via n8n.

Conclusion#

Adding feedback to a Ghost blog takes about 5 minutes with code injection. The insights are worth far more than the setup time.

If you’re running a developer blog and wondering whether your content actually helps people—add a feedback mechanism. You might be surprised what you learn.

Resources:

• SeggWat Documentation
• Ghost Integration Guide
• Widget Customization

What is a devcontainer, you may ask?#

The Dev Containers extension for Visual Studio Code lets you use a docker container as a full-featured development environment.

This is a great way to get started with a project without having to worry about the setup. It is also a great way to ensure that the code runs in a consistent environment, regardless of the developer’s local setup.

The well-known phrase “it works on my machine” best describes why you should use a devcontainer. But there are several other benefits of using it.

The benefits#

• 🚀 Easy setup: Ensures a developer can quickly set up a development environment without having to install all the dependencies and tools on your local machine.
• 🔄 Consistency: Ensures that all developers are using the same environment.
• 🧩 Reproducibility: It allows you to easily reproduce the same environment on different machines.
• 📦 Portability: Also allows to share the container with other developers, making it easy to onboard new team members.
• 📝 Version control: You can version control the devcontainer configuration, which makes it easy to track changes and roll back to a previous version if needed.
• 🔒 Isolation: A devcontainer allows you to isolate your development environment from your local machine, which can help prevent conflicts with other projects or dependencies.
• ⚙️ Customization: You can customize the devcontainer to suit your needs, including installing additional tools and dependencies.
• 🛠️ Integration with CI/CD: You can use the same container in your continuous integration and continuous deployment (CI/CD) pipeline, which can help ensure that the code is tested and deployed in a consistent environment.

How to use it?#

Installation#

First, install the Dev Containers extension in VSCode:

1. Open VSCode
2. Go to Extensions (Ctrl+Shift+X)
3. Search for “Dev Containers”
4. Install the extension from Microsoft

Creating Your First Devcontainer#

All the dependencies and tools needed to run the code are defined in a single file called devcontainer.json, located in the .devcontainer folder of your repository.

Here’s a minimal example for a Rust project:

{ "name": "Rust Development", "image": "mcr.microsoft.com/devcontainers/rust:latest", "customizations": { "vscode": { "extensions": [ "rust-lang.rust-analyzer", "tamasfe.even-better-toml" ] } }, "postCreateCommand": "cargo --version" } 

Opening Your Project in a Container#

1. Open your project in VSCode
2. Press F1 and select “Dev Containers: Reopen in Container”
3. VSCode will build the container and reopen your workspace inside it
4. That’s it! You’re now developing inside the container

Advanced Configuration#

For more complex projects, you might want to customize further:

{ "name": "Rust Full Stack", "image": "mcr.microsoft.com/devcontainers/rust:latest", "features": { "ghcr.io/devcontainers/features/docker-in-docker:2": {}, "ghcr.io/devcontainers/features/node:1": {} }, "customizations": { "vscode": { "extensions": [ "rust-lang.rust-analyzer", "tamasfe.even-better-toml", "vadimcn.vscode-lldb" ], "settings": { "rust-analyzer.checkOnSave.command": "clippy" } } }, "forwardPorts": [3000, 8080], "postCreateCommand": "cargo build", "remoteUser": "vscode" } 

This configuration:

• 🐳 Enables Docker-in-Docker for building containers inside your devcontainer
• 📦 Includes Node.js for frontend tooling
• 🔧 Pre-installs essential Rust extensions
• 🚪 Forwards ports 3000 and 8080 for web development
• ⚙️ Runs cargo build after container creation

Using Docker Compose#

For projects with multiple services (database, cache, etc.), you can use Docker Compose:

{ "name": "Rust with PostgreSQL", "dockerComposeFile": "docker-compose.yml", "service": "app", "workspaceFolder": "/workspace" } 

And your docker-compose.yml:

version: '3.8' services: app: build: . volumes: - .:/workspace:cached command: sleep infinity postgres: image: postgres:15 environment: POSTGRES_PASSWORD: postgres POSTGRES_DB: devdb ports: - "5432:5432" 

Conclusion#

Devcontainers eliminate the “it works on my machine” problem and streamline team onboarding. By committing your .devcontainer configuration to version control, you ensure every developer works in an identical environment.

Ready to try it? Create a .devcontainer/devcontainer.json in your next project and experience the difference!

Code Formatting#

Enforces consistent code style across your project. Fails if code isn’t formatted according to rustfmt rules.

rustfmt:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: dtolnay/rust-toolchain@stable
    - name: Check format
      run: cargo fmt --check

Unused Dependencies#

Identifies dependencies in Cargo.toml that your code doesn’t actually use. Keeps your dependency tree lean and reduces build times.

unused-dependencies:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: dtolnay/rust-toolchain@stable
    - name: Install cargo-machete
      uses: taiki-e/install-action@v2
      with:
        tool: cargo-machete
    - name: Check for unused dependencies
      run: cargo machete

Security Audit#

Scans your dependencies for known security vulnerabilities using the RustSec Advisory Database.

security-audit:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: dtolnay/rust-toolchain@stable
    - name: Install cargo-audit
      uses: taiki-e/install-action@v2
      with:
        tool: cargo-audit
    - name: Run security audit
      run: cargo audit

License and Dependency Policy#

Validates that all dependencies meet your licensing requirements and aren’t banned. Useful for ensuring compliance in commercial projects.

cargo-deny:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: dtolnay/rust-toolchain@stable
    - name: Install cargo-deny
      uses: taiki-e/install-action@v2
      with:
        tool: cargo-deny
    - name: Check licenses and advisories
      run: cargo deny check

Static Analysis#

Runs Clippy lints to catch common mistakes and non-idiomatic code. The -D warnings flag treats warnings as errors, forcing you to address them.

clippy:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: dtolnay/rust-toolchain@stable
    - name: Setup Rust cache
      uses: Swatinem/rust-cache@v2
      with:
        cache-on-failure: true
    - name: Check for clippy warnings
      run: cargo clippy --all-targets --all-features --color always – -D warnings

Unit Tests#

Runs tests defined alongside your code in lib files. Quick feedback on core logic.

unit-tests:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: dtolnay/rust-toolchain@stable
    - name: Setup Rust cache
      uses: Swatinem/rust-cache@v2
      with:
        cache-on-failure: true
    - name: Run unit tests
      run: cargo test --lib

Integration Tests#

Runs tests from the tests/ directory that verify multiple components working together.

integration-tests:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: dtolnay/rust-toolchain@stable
    - name: Setup Rust cache
      uses: Swatinem/rust-cache@v2
      with:
        cache-on-failure: true
    - name: Run integration tests
      run: cargo test --test integration_test

Release Build#

Verifies that your code compiles with optimizations enabled. Catches issues that only appear in release mode.

build:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: dtolnay/rust-toolchain@stable
    - name: Setup Rust cache
      uses: Swatinem/rust-cache@v2
      with:
        cache-on-failure: true
    - name: Release build
      run: cargo build --release --verbose

Caching Strategy#

The Swatinem/rust-cache action caches compilation artifacts between workflow runs. This includes:

• Compiled dependencies in target/
• Cargo registry and git checkouts
• Incremental compilation data

The cache-on-failure: true option saves the cache even when the build fails. This is useful because:

• Your code might fail tests, but dependencies still compiled successfully
• Next run will be faster even if this one failed
• Particularly helpful when fixing compilation errors incrementally

Without caching, each workflow run compiles all dependencies from scratch. With caching, only your changed code recompiles, cutting workflow time from minutes to seconds.

Putting It All Together#

Check out the complete workflow configuration on GitHub.

⚙️ VSCode REST Client#

The VSCode REST Client Extension offers a lightweight, integrated solution, running directly within your code editor. For developers seeking a seamless and efficient API testing experience, it’s an ideal alternative to traditional tools, minimizing workflow interruptions.

Key Features:

• Request Definition: Define HTTP requests using a Markdown-like syntax in .http or .rest files.
• Variable Support: Use variables to parameterize requests and responses.
• Environment Variables: Set environment variables for requests and responses.
• Version Control: Track changes to API requests over time using text-based files.
• Integration: Seamlessly integrate with VS Code, reducing window switching and maintaining consistency between requests and codebase.

🛠 Installation#

• Open VSCode and navigate to the Extensions panel.
• Search for REST Client and install the extension.

🚀 Getting Started#

To get started with the VSCode REST Client, follow these steps:

1. Create a new file with a .http or .rest extension.
2. Run the request by clicking the Send Request button.
3. View the response data in the separate panel.

Define your request using the Markdown-like syntax.

### Simple GET request

GET http://httpbin.org/get

### Simple POST request

POST http://httpbin.org/post
Content-Type: application/json

{
    "msg": "Hello World"
}

1. Create a new file with a .http or .rest extension.
2. Define your request using the Markdown-like syntax.

### Simple GET request

GET http://httpbin.org/get

### Simple POST request

POST http://httpbin.org/post
Content-Type: application/json

{
    "msg": "Hello World"
}

3. Run the request by clicking the Send Request button.
4. View the response data in the separate panel.

⭐️ Benefits#

Seamless Integration in VS Code#

Switching between applications can disrupt your workflow. The VS Code REST Client keeps everything in one place, letting you send HTTP requests and view responses directly in your code editor. By staying within VS Code, you reduce the friction of hopping between windows, which is especially beneficial if you’re working on complex projects where every saved second counts.

Variable support#

Support for variables, which can be defined in the .http or .rest files. Variables are defined using the @ symbol and can be referenced using the {{variable}} syntax. This allows you to parameterize requests and responses, making your API testing more dynamic and flexible. Environment variables

@hostname = api.example.com
@port = 8080
@host = {{hostname}}:{{port}}
@env_var = {{$dotenv [%]variableName}}

###

@name = Strunk & White

GET https://{{host}}/authors/{{%name}} HTTP/1.1

The extension also supports environment variables, which can be defined in the settings.json file. This allows you to set up different environments (e.g., local, staging, production) and switch between them easily. Environment variables can be shared across environments, making it easy to reuse values like tokens, URLs, and other constants.

"rest-client.environmentVariables": {
    "$shared": {
        "version": "v1",
        "prodToken": "foo",
        "nonProdToken": "bar"
    },
    "local": {
        "version": "v2",
        "host": "localhost",
        "token": "{{$shared nonProdToken}}",
        "secretKey": "devSecret"
    },
    "production": {
        "host": "example.com",
        "token": "{{$shared prodToken}}",
        "secretKey" : "prodSecret"
    }
}

What You’ll Build#

A simple, responsive landing page with:

• Profile photo and bio
• Links to your social profiles and projects
• Custom styling with Tailwind CSS and DaisyUI
• Free hosting via GitHub Pages

Prerequisites#

• GitHub account
• Claude Code (or any text editor)
• Basic HTML knowledge (helpful but not required)

Step 1: Create the HTML Structure#

Create an index.html file with this basic structure:

<!DOCTYPE html>
<html lang="en" data-theme="dark">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Your Name - Links</title>
    
    <!– Tailwind CSS + DaisyUI -->
    <link href="https://cdn.jsdelivr.net/npm/daisyui@4.4.19/dist/full.min.css" rel="stylesheet">
    <script src="https://cdn.tailwindcss.com"></script>
</head>
<body class="min-h-screen bg-base-200">
    <div class="container mx-auto px-4 py-8 max-w-2xl">
        <!– Profile Section -->
        <div class="flex flex-col items-center mb-8">
            <div class="avatar mb-4">
                <div class="w-32 rounded-full ring ring-primary ring-offset-base-100 ring-offset-2">
                    <img src="your-photo.jpg" alt="Profile" />
                </div>
            </div>
            <h1 class="text-3xl font-bold mb-2">Your Name</h1>
            <p class="text-base-content/70 text-center">Software Developer | Open Source Enthusiast</p>
        </div>

        <!– Links Section -->
        <div class="space-y-4">
            <a href="https://github.com/yourusername" 
               class="btn btn-lg btn-block btn-primary">
                GitHub
            </a>
            
            <a href="https://twitter.com/yourusername" 
               class="btn btn-lg btn-block btn-secondary">
                Twitter
            </a>
            
            <a href="https://your-blog.com" 
               class="btn btn-lg btn-block btn-accent">
                Blog
            </a>
            
            <a href="mailto:you@example.com" 
               class="btn btn-lg btn-block btn-ghost">
                Email
            </a>
        </div>
    </div>
</body>
</html>

Step 2: Customize with Claude Code#

You can use Claude Code to generate variations or add features:

# Ask Claude Code to customize your page
claude "Add a projects section with cards showing my GitHub repos"
claude "Change the theme to light mode with custom colors"
claude "Add icons from Heroicons to each link button"

Claude Code can help you:

• Add custom sections (projects, skills, testimonials)
• Implement dark/light theme toggle
• Add animations or transitions
• Integrate analytics

Step 3: Customize Styling#

DaisyUI provides several built-in themes. Change the data-theme attribute:

<html lang="en" data-theme="cyberpunk">

Available themes: light, dark, cupcake, cyberpunk, valentine, synthwave, retro, and many more.

You can also create custom color schemes by adding a config:

<script>
    tailwind.config = {
        daisyui: {
            themes: [
                {
                    mytheme: {
                        "primary": "#your-color",
                        "secondary": "#your-color",
                        "accent": "#your-color",
                    },
                },
            ],
        },
    }
</script>

Step 4: Setup GitHub Repository#

1. Create a new repository named username.github.io (replace with your GitHub username)
2. Clone the repository locally
3. Add your index.html file
4. Commit and push:

git add .
git commit -m "Initial biolink page"
git push origin main

Step 5: Enable GitHub Pages#

1. Go to your repository on GitHub
2. Click Settings → Pages
3. Under “Source”, select “Deploy from a branch”
4. Select “main” branch and “/ (root)” folder
5. Click Save

Your site will be live at https://username.github.io within a few minutes.

Step 6: Add Custom Domain (Optional)#

If you own a domain:

1. In your repository, create a file named CNAME with your domain:

yourdomain.com

2. Add DNS records at your domain provider:

Type: A
Name: @
Value: 185.199.108.153

Type: A
Name: @
Value: 185.199.109.153

Type: A
Name: @
Value: 185.199.110.153

Type: A
Name: @
Value: 185.199.111.153

3. In GitHub Pages settings, enter your custom domain and enable HTTPS

Advanced Features You Can Add#

Use Claude Code to implement:

• Analytics: Track visitors with Plausible or Google Analytics
• Dynamic content: Fetch GitHub stars or latest blog posts via API
• Contact form: Use Formspree or Web3Forms for free form handling
• SEO optimization: Meta tags for better social media sharing
• QR code: Generate a QR code linking to your page

Example Implementation#

Check out a complete example on GitHub.

Conclusion#

You now have a completely free, customizable BioLink page that you control. No monthly fees, no feature limits, and you can modify it however you want. Update it by editing the HTML and pushing to GitHub - changes go live in seconds.

Learn more about scd4x here.