DEV Community: martinimarcello00

I put an LLM agent on a static site for free. Here is the actual bill

martinimarcello00 — Thu, 10 Sep 2026 15:22:35 +0000

The previous post made a claim I still stand behind: this site has no server, no database and nothing to patch. It is a repository that becomes HTML.

Then there is a button in the bottom right corner that answers questions about me, in full sentences, out of a language model. Both things are true at the same time. The second one is only free at the point where you happen to be looking.

Where the agent actually runs

Not here. It is a Docker image on a Hugging Face Space, on the free CPU tier, two shared cores. A GitHub Action pushes the repository to the Space on every commit to main, so shipping the agent is still git push, the same gesture that ships the site.

The site's half of the contract is one line:

export const CHAT_ENDPOINT = 'https://martinimarcello00-personal-cv-langgraph.hf.space/chat';

That is the whole dynamic part of a static site. Everything in dist/ is still a file, and the one thing that thinks lives somewhere else behind a URL. The architecture did not get simpler. It moved.

Free means it falls asleep

A free Space sleeps after 48 hours without traffic, and only paid hardware can be told not to. The next visitor restarts it, which sounds harmless until you read what the container does when it boots:

CMD ["/bin/bash", "-c", "python build_rag.py && uvicorn api:app --host 0.0.0.0 --port 7860"]

The vector index is not baked into the image. It is rebuilt at startup, every document re-embedded with bge-small-en-v1.5 on those two shared cores before the first request gets an answer. Somebody arriving after a quiet weekend is not waiting for a container to start. They are waiting for an embedding job to finish.

So the Space is never allowed to be idle. The monitor that already watches the containers on my home server watches this one too.

Uptime Kuma — The thing that notices before I do.

Scheduled checks against the handful of endpoints that are supposed to answer, with a notification when one stops. The job I did not expect to give it is keeping something awake rather than watching it: a free Hugging Face Space sleeps after two days of silence, and a periodic request to its health check is what stops the assistant on this site from booting cold in front of a visitor.

The detail that makes it cheap is the target. api.py exposes a health check next to the chat endpoint:

@app.get("/health")
def health_check():
    return {"status": "ok"}

The monitor calls /health every five minutes and never calls /chat. It costs a TCP connection and zero tokens. Pointing a keepalive at the chat endpoint instead would mean paying a language model 288 times a day, forever, to tell a machine that it is still awake.

Five minutes against a threshold of 48 hours is far more often than the problem requires, and I am keeping it, because a check that frequent is also answering the question the monitor was installed for: not only is the agent awake, it is reachable, and I find out before a visitor does.

That is the first tradeoff and it deserves saying plainly: the free tier is free because it expects to be idle, and I am using hardware I own to guarantee that it never is. Somebody else's free hosting, kept alive by my electricity bill.

The bill is the real limit

Sleeping is an inconvenience. The API is the part that can actually cost money, because every visitor is spending mine.

Two of the three guards are the ones everybody writes. A rate limit per address:

@app.post("/chat")
@limiter.limit("5/minute")

And a CORS list with my domain on it, which is worth being honest about. It stops a script on another site from using my endpoint from somebody's browser, and it stops nothing else. The Space has its own public interface one click away, and CORS was never an authentication mechanism.

The third guard is the one I would copy into any project shaped like this one. Before answering anything, the app asks the provider how much it has already spent today:

usage = get_today_model_usage("gpt-5-nano")
if usage.get("total_tokens", 0) >= daily_limit:
    return {"response": "I'm currently overwhelmed with fame (and API token limits)..."}

The budget is not a counter in a variable that resets when the container restarts. It is the organization usage endpoint, for the current UTC day, grouped by model. A crash does not hand out a fresh allowance, and neither does a redeploy.

Notice what the visitor gets when it runs out. A joke, not a 429. When a failure is guaranteed to happen eventually and it is not the visitor's fault, the degraded state stops being an error path and becomes a copy decision.

What the budget buys, and what it costs

The choices that make that budget last are all visible in the code, and they are the same choices that decide how the thing feels. The model is gpt-5-nano. Memory is get_safe_history(messages, k=4), the last four messages, walked further back if the cut would land in the middle of a tool call. Retrieval mixes vectors with BM25, and the BM25 half is rebuilt from every document in the store on each query.

From the comment I left in the widget after measuring it: 17 seconds for a cold question, over 25 for a follow-up. Follow-ups are slower than first questions, which is the opposite of what anyone expects, because the thread travels with the request.

There is a stranger consequence hiding in the same file. The checkpointer is MemorySaver, which lives in the process. The browser stores a thread id and keeps the transcript, so a conversation survives navigation, a reload and my next deploy. The agent's copy of it does not survive the restart. The visitor is holding a conversation the server has already forgotten, and it looks fine right up until it does not.

The front end pays whatever is left

None of that can be fixed for free, so the interface has to absorb it.

const killTimer = window.setTimeout(() => controller.abort('timeout'), 90000);

Ninety seconds before giving up, a counter that appears once the wait passes five, and a line under the typing dots that says what is going on: "Still thinking, 12s. It runs on a free box and takes its time."

Naming the constraint costs nothing and changes the entire reading of the wait. Twenty five silent seconds are indistinguishable from something broken. The same twenty five seconds with a number attached are a slow machine, which is exactly what it is.

The obvious next move is already half built. api.py also exposes /chat/stream, and the site does not call it. The wait would stop being one opaque block and start being text arriving. That is a commit, not a subscription.

What actually came back

The site is still static. Nothing returned that I have to patch, back up or keep running. What returned is a budget, a monitor and a sentence admitting the box is free.

Free hosting for something that thinks is real, and this is the price on the label: it sleeps unless something wakes it, it forgets unless somebody pays for memory, it is slow unless the answer is cheap, and it stops when the day's tokens are gone. All four are acceptable for an assistant on a personal site. None of them are invisible, and pretending otherwise is how you end up with a chat button that has been broken for a week before anyone bothers to tell you.

How the agent is built

This one first appeared on my site, where I write about the systems I build and the tools I actually use — the rest of the posts live here.

Real HTTPS for self-hosted services, without opening a single port

martinimarcello00 — Tue, 01 Sep 2026 07:33:33 +0000

My home server is an old desktop with four cores and 8 GB of RAM running OpenMediaVault, and it has thirty three containers up right now. A third of them are the usual media stack, which the internet has documented to death, so this is about the interesting part: of those thirty three, only two decide what is reachable and by whom.

Nothing listens on my network

Almost every compose file on that machine has the same shape:

services:
  immich-server:
    ports:
      - "127.0.0.1:2283:2283"

That prefix is the entire security model. The port exists on loopback only, so no device on my LAN can reach the container by address, not even by accident, and a container I misconfigure cannot quietly become a public service.

Two containers break the rule on purpose. Pi-hole, because it has to answer DNS on port 53 for the whole house, and Nginx Proxy Manager, which owns 80 and 443. Everything else is reachable only if the proxy has been told a hostname for it.

Nginx Proxy Manager — One door in front of thirty containers.

Every service on my home server binds to loopback, so this proxy is the only way in and the only place that decides what exists. It terminates HTTPS with real Let's Encrypt certificates issued over the DNS challenge, which means hostnames that resolve to a private address still get a genuine padlock instead of a self-signed warning. Adding a host takes two minutes in the web UI, which is the reason the loopback rule never gets bent.

HTTPS for names the internet cannot reach

Internal services live on subdomains of a domain I own. Those DNS records are public, and they answer with the private address the server holds on my LAN. Anyone can resolve the name; nobody outside the flat can route to it.

That is also what makes the certificates work. Nginx Proxy Manager asks Let's Encrypt over the DNS challenge, which proves I control the domain by writing a TXT record rather than by accepting an inbound connection. A service the internet cannot reach therefore still gets a genuine certificate: no self-signed warnings, no private CA to install on every phone, a normal padlock everywhere.

Pi-hole answers those names on the LAN and blocks ads for every device while it is at it, including the ones that will never run an extension.

Two things break this, and neither is in the tutorials.

The first is DNS rebinding protection. A resolver that guards against it throws away any answer pointing at a private address, which is exactly what my records do, so the name resolves to nothing and the service looks dead. Plenty of routers ship with the protection on, dnsmasq and Pi-hole can do the same, and the fix is to whitelist the one domain rather than to switch the whole thing off.

The second is the browser. Firefox and Chrome will happily send DNS over HTTPS to a public resolver, walking straight past the machine that knows the internal names. Everything works on one laptop and fails on another, and the difference is a setting nobody remembers changing.

The price of the DNS challenge is worth saying out loud too: an API token for the DNS provider now lives on the server. Scope it to the single zone it needs, never to the account.

The VPN is the way in

Tailscale runs as a container advertising the route of my home subnet. My laptop and my phone are on the same mesh, so away from home they resolve and reach exactly the same hostnames as they do from the sofa, over WireGuard, with the certificates still valid.

The router has no port forwarding, no dynamic DNS and no UPnP. The attack surface of the whole setup is one Tailscale identity.

Tailscale — My machines behave as if they were on one LAN.

A WireGuard mesh across my laptop, phone and home server, so the self-hosted things stay off the public internet while remaining one hostname away from anywhere. It removed the last reason I had to open a port on my router.

The one exception, and it dials out

Webhooks are the case a VPN cannot solve: a third party has to POST to a URL that really exists on the internet. That single hostname goes through a Cloudflare tunnel. The container opens an outbound connection to Cloudflare, Cloudflare terminates TLS at the edge and pushes requests back down the same connection to n8n. One name is public, my address is not, and there is still nothing listening at home.

What runs behind all that

Home Assistant is the container I would restore first. Every sensor, plug and light in the flat talks to it locally, so the house does not stop working when the line does, and a year of energy readings sits on my disk instead of in someone's analytics pipeline. ESPHome compiles the firmware for the cheap microcontrollers I use as sensors, a Matter server handles the devices that speak it, and n8n deals with whatever has to leave the house.

Home Assistant — The house runs locally or it does not run.

Every sensor, plug and light talks to a container in my flat rather than a vendor cloud, so automations keep working when the internet is down and the history stays on my disk. Integrations cover the devices I already owned, and ESPHome turns a five euro microcontroller into a first class sensor with a few lines of YAML.

The rest is what I open every day. Immich replaced Google Photos properly, faces and search included. Karakeep archives the links I mean to read, with Meilisearch behind it. Calibre-web feeds the Kindle. Five small containers watch the others: Portainer, Dozzle for logs, Beszel for CPU and temperature history, What's Up Docker for image updates, and Homepage as the front page that ties them together.

The unglamorous half

None of this matters if the disk dies, and exactly one container holds something I cannot download again. The photos are the only irreplaceable data on the machine; everything else is a compose file, a config directory and an afternoon.

So Immich is treated differently. Borg backs it up to a Hetzner storage box, encrypted before it leaves the house and deduplicated, so keeping a long history costs almost nothing and a bad run cannot quietly overwrite the good copies. The compose files ride along in the same archive, which is what turns "rebuild the server" from a project into a chore.

Immich — The photo library that stopped being rented.

BorgBackup — The only container whose failure would actually hurt.

Two containers out of thirty three do the work that matters: the proxy that decides what exists and the VPN that decides who is inside. One backup covers the only data that cannot be recreated. Everything else is replaceable in an afternoon, which is the whole point of building it this way.

Home Assistant is the oldest thing on that machine by a decade. The lights, sensors and buttons it drives started on a Raspberry Pi in 2017 and moved here once the server existed, and that side of the house is written up separately under Home automation.

See the full toolbox

This one first appeared on my site, where I write about the systems I build and the tools I actually use — the rest of the posts live here.

I moved my site from Hugo to Astro and kept every URL

martinimarcello00 — Tue, 25 Aug 2026 17:46:44 +0000

Every personal site I built before this one died the same way. A CMS I stopped updating, a database I had to back up, a plugin that broke on a version bump. The fix was to make the site something I already maintain every day: a repository.

That part has not changed. There is still no server, no database, nothing to patch. What changed is the thing that turns the text files into HTML.

Why I left Hugo

Hugo — A website that is just files in a repository.

Still the fastest thing I have used for a site that is only pages. A full rebuild in about four hundred milliseconds, which spoils you.

Not for speed. Hugo rebuilt this entire site in roughly four hundred milliseconds. Astro takes about thirteen seconds for forty four pages. On that number alone I should have stayed.

I left because of what the site had become. It was no longer only pages. There was a chat widget, a photo slideshow with filters, a travel map, a search modal, a theme toggle, a consent banner. Every one of them was hand written JavaScript in a <script> tag, reaching into markup produced by a Go template that knew nothing about it. Nothing checked that the class a script queried still existed. Nothing checked that a field a template read was still in the YAML.

The trigger was mundane. I renamed a key in a data file and a section quietly vanished from three pages, because Go templates resolve a missing field to the empty string and carry on. That is correct behaviour for a template engine. It is a bad property for a site with a hundred interlocking data fields.

The rule: not a single URL changes

Before writing any code I set one constraint. Every URL the old site served, the new one serves, at the same address, or the migration failed.

Two settings carry most of that:

build: { format: 'directory' },
trailingSlash: 'always',

Hugo published everything as <route>/index.html with a trailing slash. Keeping both means no redirect layer and no changed link.

The interesting one was casing. Hugo ran with disablePathToLower, so a file named SE2-Project.md was served at /projects/SE2-Project/. Astro's content loader lowercases ids by default, which would have moved that page and broken every inbound link to it without anything looking wrong:

const verbatimId = ({ entry }: { entry: string }) => entry.replace(/\.mdx?$/, '');

The sitemap stayed hand written for the same reason. The official integration publishes sitemap-index.xml, and Search Console already knows this site's sitemap as /sitemap.xml. Writing it myself also lets each entry carry a real lastmod taken from the git history rather than the build date, which is the more honest answer to when a page last changed.

What did not move at all

The content did not. Posts and projects are the same Markdown files with the same front matter. The data/ directory is byte for byte the same YAML and JSON. The Python scripts that refresh publications from ORCID, repositories from GitHub and book covers from Open Library were not touched, because they write JSON and do not care who reads it.

That is the part worth stealing. The migration was survivable because the content and the data were never coupled to the tool. Only the layer that renders them was.

GitHub Actions — The only deploy button, and it is a git push.

The workflow kept its most useful property too:

- name: Refresh auto-updating data
  # Non-fatal: on API failure the committed data/*.json is used as fallback
  continue-on-error: true
  run: python3 scripts/update_data.py

The generated JSON is committed. If ORCID is down the step goes red, the build carries on, and the site shows yesterday's data. A stale publication list beats a failed deploy.

Islands, and the pages that ship nothing

Astro — Components everywhere, JavaScript only where it earns it.

A site framework that renders to HTML at build time and ships no client JavaScript unless a component asks for it. The interactive pieces are marked as islands and hydrate on their own; everything around them stays static. It also types the content: Markdown front matter and the data files are parsed through a schema during the build, so renaming a field is an error rather than a silently empty section.

The reason to be on Astro is that a page ships no JavaScript unless something on it needs JavaScript. The interactive parts are components marked as islands. Everything else is HTML produced at build time and then left alone.

So the photo wall, the chat panel, the tool filters and the search dialog hydrate. The about page, the posts and the project pages ship markup and CSS and nothing else. It is the component model without the tax I expected to pay for it.

The clearest measurement of that is the diagram library, further down.

The data files got a type, and immediately caught me

Every file under data/ is now parsed through a Zod schema at build time. Renaming a key is a build error instead of a blank section, which is exactly what I wanted.

It also introduced a new way to be wrong, and I walked into it within a week. A tool card silently lost its link. No error, no warning, a green build. The schema declared the field as internal, the JSON called it internal_url, and Zod strips keys it does not recognise without saying anything. The value was read, discarded, and rendered as nothing.

That is the shape of most bugs I hit in this migration, and it deserves a name: a wrong name produces nothing, not an error. A CSS custom property that does not exist, a Tailwind class whose token is not defined, a schema key that does not match the data. All three compile. All three render silence. None appear in a console. The only thing that catches them is reading the computed value in the browser.

Social cards, drawn differently

Every page still gets its own 1200x630 preview image, still drawn during the build, still without a headless browser taking screenshots.

Hugo did it with images.Text, stamping the title onto a base image. That function does not wrap, so the template split the title into lines by hand, and the variable font rendered at its lightest weight, so I drew the text three times at one pixel offsets to fake a bold.

Astro has no equivalent, so the card is now laid out with Satori, which takes something shaped like JSX and produces SVG, then rasterised with resvg. Text wraps because flexbox wraps, and both hacks above disappeared. The cost is a real dependency where there had been a built in function.

Search did not change

Pagefind still reads the finished HTML after the build and writes an index next to it. It never cared which generator produced the HTML, which is precisely why it survived the move untouched.

One attribute still decides what is indexed, and it is also how the pages I keep out of search stay out of it:

data-pagefind-body={noindex ? undefined : true}

Press cmd+K anywhere on the site and it opens.

Code blocks, and a bug that was invisible by design

Astro highlights code with Shiki at build time, so no highlighting library reaches the browser. Configure two themes and it writes both into the markup: the light one as inline styles, the dark one as CSS custom properties.

I configured both, opened a post in dark mode, and the code was still light. There was nothing to debug. Forty two code blocks, two hundred and sixty three --shiki-dark variables sitting in the HTML, and not one rule reading them. Emitting the variables is Shiki's half of the job. Consuming them is yours:

html.dark .astro-code,
html.dark .astro-code span {
  color: var(--shiki-dark) !important;
}

Two details are specific to Astro. The class is .astro-code, not Shiki's .shiki, so every example you find online needs renaming. And the switch has to key off whatever your theme toggle sets rather than prefers-color-scheme, or the blocks follow the operating system while the rest of the page follows the button.

Diagrams, three times

The single architecture diagram on this site has now been rendered three different ways.

Under Hugo it pulled Mermaid from a CDN on every page carrying the shortcode. During the migration I stubbed the renderer to return nothing, meaning to come back to it, and the diagram shipped as preformatted text for weeks. The stub was one line and it never complained.

It now uses an integration that renders in the browser, which sounds like a step backwards until you check where the cost lands:

mermaid({ theme: 'neutral', autoTheme: true }),

I watched the network on three pages. The privacy page and a blog post make zero requests for Mermaid. The one project page holding a diagram makes one. Ninety six kilobytes, paid by the single page that needs it.

The build got slower for it, from about ten seconds to thirteen. For one diagram that is the right trade only because the alternative, rendering to SVG during the build, needs a headless browser installed in CI. If this site ever has twenty diagrams, that calculation flips.

A full copy of the site, before it is the site

Cloudflare Pages — A full copy of the site to look at before anyone else can.

Static hosting on Cloudflare's edge, used here for staging rather than production. Every push to a branch that is not master builds the whole site and publishes it to a separate hostname, so a redesign can be read on a real phone over real HTTPS instead of on localhost. The preview is served with a noindex header so it never competes with the live site in search results.

A rewrite lives on a branch for weeks, and reading it on localhost is not the same as reading it on a phone, on a real connection, over real HTTPS. Half the layout bugs in this migration only appeared once the site was somewhere I could open from the sofa.

So production stays on GitHub Pages and every push to a branch that is not master builds the whole site and publishes it to a separate host:

on:
  push:
    branches-ignore: ["master"]

The part I would not skip is the one line that keeps a full duplicate of the site out of search results:

printf '/*\n  X-Robots-Tag: noindex, nofollow\n' > dist/_headers

Without it you have published a second copy of every page, with the same text and different URLs, and invited a search engine to choose between them. The header is unconditional, so there is no configuration to get wrong later.

The workflow also checks its credentials before it builds rather than after, so a missing secret fails in a few seconds instead of at the end of a full build. That one is a small thing that pays for itself the first time it happens.

What Copilot was good for

GitHub Copilot — A fast first draft, never the final word.

Used the way it is good: a fast first draft on code I can review, never on decisions I have not made yet.

A migration is mostly translation, and translation is what these tools are genuinely good at. Turning a Go template into an Astro component is mechanical work with a right answer, and having it drafted saved real hours.

Where it helped least is exactly where this post keeps landing. It writes code that compiles and renders nothing, for the same reason I do: the wrong token name and the right token name look equally plausible. All three of the silent bugs above survived review, mine and its, and died to a measurement in the browser.

GitHub — Version control is the least interesting part.

The crosspost that cannot duplicate itself

A post opts in to dev.to with one line of front matter:

devto: true

A script renders it, rewrites the components into portable Markdown and sends it with a canonical_url pointing back here, so the copy never competes with the original in search results.

The hard part was running it from CI, where there is no local state. Before sending anything the script asks dev.to what the account already holds and indexes it by canonical URL, so an article that exists is updated and never created twice, even on a fresh runner. The state file is only a cache plus a hash of the Markdown last sent, which is what stops an unchanged post being pushed back to the top of the feed on every deploy.

Two things bit me there. dev.to renders Markdown with hard wrapping on, so my eighty column source lines each became a <br>, which is why paragraphs are unwrapped before they are sent. And the API returns 429 well before its documented limits, so writes are spaced out and retried on the Retry-After header.

If you are reading this on dev.to, that is how it got here, and this is the second version of it.

Was it worth it

For the pages, no. Hugo rendered them faster and no reader can tell the difference.

For everything else, yes. The interactive parts are components with props instead of scripts hunting for selectors, the data files have a type, and the things that were held together by convention now fail at build time when I break them. That is what I actually bought, and it is worth thirteen seconds.

What I would tell myself before starting: pin the URLs first and treat any change to one as a bug, keep the content and the data independent of whatever renders them, and do not trust a green build. Three of the bugs in this post produced no error at all.

The rest of the toolbox

This one first appeared on my site, where I write about the systems I build and the tools I actually use — the rest of the posts live here.

3 small tools that changed how I work every day

martinimarcello00 — Tue, 25 Aug 2026 15:38:09 +0000

Most "my setup" posts are shopping lists. This one is not, because the tools below earned their place by surviving contact with a bad week: a deadline, a broken laptop, a paper due, an evening where I could not stop scrolling. Everything else got uninstalled.

Three of them are worth telling properly.

chezmoi: my machine is a git clone

I used to keep dotfiles in a repo with a install.sh that symlinked things into place. It worked right up until my laptop and my home server needed almost the same configuration: same aliases, different git email, different paths, and one of them absolutely must not carry a work SSH config.

chezmoi solves exactly that. The dotfiles live in one repository, the machine-specific bits are templates, and secrets are pulled from a password manager at apply time instead of sitting in git. Bootstrapping a new machine is now one command and a coffee.

The unglamorous benefit is the one I care about: I stopped being afraid of reinstalling. When the setup is a git clone away, wiping a machine is a chore rather than a decision.

chezmoi — Dotfiles in git, secrets left out of it.

Keeps my shell, editor and git configuration in one repository and templates the parts that differ per machine, so a work laptop and a home server share a setup without sharing their secrets. Bootstrapping a new machine is a single command instead of an afternoon of copy-paste.

Atuin: my shell history became searchable

Every developer has a moment of typing history | grep and hoping. Shell history is one of the most valuable datasets you generate, and by default it is a flat file that truncates, forgets which directory you were in, and vanishes when you open two terminals at once.

Atuin replaces Ctrl-R with a real search over a SQLite database of every command, recorded with its directory, its exit code and how long it took. It syncs end-to-end encrypted between machines, and you can run the sync server yourself if you would rather not trust anyone with it.

What changed is subtle. I stopped writing throwaway shell scripts for things I do twice a year, because "the ffmpeg command from that conference talk" is now a two-second lookup instead of an archaeology project.

Atuin — Shell history as a searchable database.

Replaces Ctrl-R with a real search over every command I have ever run, recorded with its directory, exit code and duration. History syncs end-to-end encrypted between my laptop and my servers, and you can host the sync server yourself. The obscure ffmpeg invocation from eight months ago is now a two-second lookup.

A brick, and the app behind it

The one that is not software. I was properly hooked on my phone: in hand before my eyes were open, thumb scrolling through dinners and lectures. Willpower never fixed it.

What fixed it was a small orange square on my desk, a magnet and an NFC tag. Tap the phone against it and the apps I chose disappear. Tap again and they come back, but only if I walk to wherever I left the brick. That tiny bit of friction is the entire trick.

Underneath it is Foqos, an open-source iOS app that ties Apple's Screen Time restrictions to an NFC tag. No account, no subscription, no streak to protect. Two weeks in, my screen time had halved and I had stopped missing it, which says more about the reflex than about the willpower.

Focus Brick — A magnet, an NFC tag, two taps.

Foqos — The open-source app behind the brick.

The rest of the toolbox

These three are the ones with a story. The rest of what I use every day lives on the toolbox page: editor, terminal, research and focus tools, each with a note on why it earned its place, filterable by category.

See the full toolbox

Nothing here is sponsored and nothing is permanent. If one of these stops earning its place, it comes off the list.

This one first appeared on my site, where I write about the systems I build and the tools I actually use — the rest of the posts live here.

My entire terminal setup restores from one git clone

martinimarcello00 — Tue, 25 Aug 2026 15:27:05 +0000

I spend more hours in a terminal than in any other window, and for years the configuration behind it lived nowhere: a .zshrc I had edited so many times I no longer knew which line did what, a colour scheme picked in a preferences dialog, an SSH config that only existed on one laptop.

What follows is what that turned into. Not a list of everything installed on my Mac, but the terminal I actually type in and the two-part trick that keeps it reproducible: every setting is a plain-text file, and every plain-text file is in a repository.

The terminal: Ghostty

I moved off iTerm2 because I wanted a terminal that was fast and, more importantly, one whose entire appearance I could describe in text.

Ghostty — A fast terminal with no tabs of its own to manage.

Native on macOS, GPU-accelerated, and quick enough that a long build log scrolls without the fan spinning up. The configuration is a single plain-text file with one setting per line, which means the whole appearance of my terminal is a handful of lines in my dotfiles rather than a screenshot of a preferences pane I would have to redo on the next machine.

Ghostty's config is a single file, ~/.config/ghostty/config.ghostty, with key = value on each line and # for comments. That is the whole format:

theme = dracula
font-family = "MesloLGS NF"
font-size = 14
window-padding-x = 8
window-padding-y = 6
macos-option-as-alt = true
copy-on-select = true

The interesting part is theme. A Ghostty theme is just another config file, so any file dropped in ~/.config/ghostty/themes/ can be selected by name. Mine is Dracula and starts like this:

palette = 0=#21222c
palette = 1=#ff5555
palette = 2=#50fa7b
background = #282a36
foreground = #f8f8f2
cursor-color = #f8f8f2
selection-background = #44475a

Sixteen palette entries and a handful of colours: that is the difference between "my terminal looks right" and "my terminal looked right on the old machine". cmd+shift+, reloads the config without restarting, so tuning it is a live loop rather than a quit-and-relaunch cycle.

The shell: zsh, Oh My Zsh, Powerlevel10k

macOS ships zsh, Oh My Zsh handles plugin loading, and Powerlevel10k draws the prompt.

Oh My Zsh — A shell that tells me where I am.

Two lines do most of the work in my .zshrc:

ZSH_THEME="powerlevel10k/powerlevel10k"
plugins=(git zsh-syntax-highlighting z fzf-tab)

Those four plugins are the ones that survived. git for the aliases and the branch state, zsh-syntax-highlighting because a command turning red before I press Enter has caught more typos than I would like to admit, z to jump to a directory I visited last week by typing three letters of its name, and fzf-tab to hand tab-completion over to fzf, turning a wall of candidates into a fuzzy-searchable list.

Powerlevel10k is configured with p10k configure once, and the wizard writes ~/.p10k.zsh — which then goes into the dotfiles repo like everything else. Mine runs in nerdfont-v3 mode with the lean prompt, which means the prompt shows the git branch, the Python environment and the exit code of the last command. Most of my terminal mistakes used to be context mistakes: wrong branch, wrong virtualenv, wrong machine.

One detail that is easy to miss: the p10k instant-prompt block has to stay at the very top of .zshrc, above anything that might print or ask for input. It is the reason the prompt appears immediately instead of after the plugins finish loading.

History that is actually searchable

The single biggest upgrade is not the prompt. It is replacing Ctrl-R with something that remembers.

Atuin — Shell history as a searchable database.

Replaces Ctrl-R with a real search over every command I have ever run, recorded with its directory, exit code and duration. History syncs end-to-end encrypted between my laptop and my servers, and you can host the sync server yourself. The obscure ffmpeg invocation from eight months ago is now a two-second lookup.

One line in .zshrc:

eval "$(atuin init zsh)"

After that, every command is recorded in SQLite along with its directory, exit code and duration, and Ctrl-R becomes a real search across all of it — end-to-end encrypted between machines, with a sync server you can host yourself.

The small stuff that adds up

Aliases live in their own file rather than sprawling through .zshrc, sourced at the end:

if [ -f ~/.zsh_aliases ]; then
    source ~/.zsh_aliases
fi

Most of them are unremarkable — gs, ga, gc, gp for git, grep --color=auto, rm -i because I would rather be asked. The ones I actually notice are the navigation shortcuts:

alias .="cd .."
alias ...="cd ../../.."
alias ....="cd ../../../.."

Two more lines worth stealing. micro as the editor, because I want a terminal editor that behaves like every other text field when I am editing a commit message at 11pm:

export EDITOR='micro'
export VISUAL='micro'

And the binding that opens the current command line in that editor, which turns a long unreadable one-liner into something you can actually see:

autoload -U edit-command-line
zle -N edit-command-line
bindkey '^x^e' edit-command-line

Making all of it reproducible

Everything above is text files. The part that makes it a setup rather than a collection is chezmoi.

chezmoi — Dotfiles in git, secrets left out of it.

Keeps my shell, editor and git configuration in one repository and templates the parts that differ per machine, so a work laptop and a home server share a setup without sharing their secrets. Bootstrapping a new machine is a single command instead of an afternoon of copy-paste.

My dotfiles repository maps one-to-one onto my home directory — dot_zshrc becomes ~/.zshrc, dot_config/ghostty/themes/dracula becomes ~/.config/ghostty/themes/dracula — plus three scripts that only run the first time chezmoi is applied on a machine:

one installs Homebrew if missing and runs brew bundle against a Brewfile that carries every formula, cask, App Store app and VS Code extension;
one clones Oh My Zsh, Powerlevel10k, fzf-tab and zsh-syntax-highlighting into the right places;
one applies the macOS defaults I would otherwise click through in System Settings — dark mode, Dock size, Finder path bar, key repeat.

The naming does the work: a file called run_once_install-deps.sh runs once and chezmoi remembers its hash, so applying the dotfiles again does not reinstall Homebrew.

Secrets stay out of the repository

The reason a dotfiles repo usually stops at "shell config" is SSH keys. chezmoi solves that with templates: a managed file can call out to a password manager at apply time. My signing key is a two-line file in the repo that contains no key at all:

{{- (bitwarden "item" "ssh-git-signing").sshKey.privateKey }}

The public keys and ~/.ssh/config are committed as plain files, the private halves are rendered from Bitwarden at apply time and never touch git. The same mechanism fills in per-machine values — my .chezmoi.toml.tmpl pulls a few cloud subscription IDs from a Bitwarden item so the helper scripts in ~/.local/bin know which subscription to talk to without those IDs living in a public repo.

Once the keys are in place, git signs commits with SSH rather than GPG, which is three lines and no keyring:

[user]
    signingkey = ~/.ssh/id_ed25519_signing.pub
[gpg]
    format = ssh
[commit]
    gpgsign = true

A new machine, start to finish

# 1. Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. The three tools needed to bootstrap the rest
brew install chezmoi bitwarden-cli gh

# 3. Auth: gh for the private repo, Bitwarden for the secrets
gh auth login && gh auth setup-git
bw login && export BW_SESSION="$(bw unlock --raw)"

# 4. Everything else
chezmoi init --apply gh:<user>/dotfiles
exec zsh

Step two is the whole bootstrap surface: chezmoi, the Bitwarden CLI and the GitHub CLI. Step four clones the repo, installs the Brewfile, applies the macOS defaults and renders every dotfile including the secrets. It takes as long as Homebrew takes.

Day to day it stays out of the way: chezmoi edit ~/.zshrc to change something, chezmoi diff to see what would change, chezmoi apply to commit to it, chezmoi update on the other machine to pull it down.

The part that is still manual

Powerlevel10k needs a Nerd Font, and mine is not in the Brewfile — I installed MesloLGS NF by hand at some point and never went back. So on a fresh machine the prompt comes up with boxes where the icons should be until I fix it, which is exactly the kind of thing this whole setup is supposed to prevent. It is one line:

cask "font-meslo-lg-nerd-font"

Which is a decent summary of how this works in practice. The setup is not finished and never will be; it just gets one line less manual every time something annoys me enough.

See the full toolbox

This one first appeared on my site, where I write about the systems I build and the tools I actually use — the rest of the posts live here.