Clicking around in a deployment platform is the wrong interface for that. I want deployment to be visible in the repo, scriptable from a terminal, and predictable when several agents are working at once.
For my current setup, Kamal is enough.
My current pattern is simple: one Hetzner server, Docker containers, Kamal configs in each repo, and PostgreSQL on the same box.
The setup is intentionally small: one solo operator running small products that need to stay cheap and understandable.
The repo evidence is plain:
web, backend, and api roles to the same host.web, backend, feed, and worker roles to the same host.AGENTS.md says it migrated from Render to Hetzner with Kamal 2 on April 8, 2026.I don’t set up a new database server for every tiny product. MyOG was the first project in this setup, so it owns the shared server pieces. The newer projects follow the pattern instead of inventing their own.
MyOG.social has the older Kamal setup in my repos. Its history shows the move in December 2025:
2025-12-20 Add Kamal 2 deployment configuration for Hetzner with PostgreSQL, Vector logging, SSL, and pre-rendering support
2025-12-19 Remove legacy render.yaml now using Kamal on Hetzner
The config is what I like about Kamal. The deployment state is a file:
service: myog
servers:
web:
hosts:
- <server-ip>: frontend
backend:
hosts:
- <server-ip>: backend
proxy:
ssl: true
host: backend.myog.social
app_port: 3001
api:
hosts:
- <server-ip>: api
proxy:
ssl: true
host: api.myog.social
app_port: 3002
accessories:
postgres:
image: postgres:16-alpine
host: <server-ip>
vector:
image: timberio/vector:latest-alpine
host: <server-ip>
I trimmed that snippet, but the important parts are there: roles, host, proxy, app ports, accessories.
Kamal’s own docs describe the same model: roles live under servers, accessories are managed separately from the app, and the proxy routes traffic to the new container after the health check passes.
That maps well to how I want agents to work. If a deploy fails, the agent can read config/deploy.yml, compare it with the Dockerfile and runtime scripts, inspect logs, and make a repo change.
No special dashboard integration needed.
TheBlue.social moved later, after the MyOG setup had already proved itself.
Its AGENTS.md records the date directly:
Migrated from Render to Hetzner (Kamal 2) on 2026-04-08.
Shares the Hetzner server and Postgres accessory
with MyOG.social and AltCaption.com.
TheBlue is also a good example of the pattern growing without turning into a platform.
It started as a web/backend app, then picked up more moving parts: feed service, background workers, and a lot of pre-rendered SEO pages. The Kamal setup split with it:
config/deploy.yml # web
config/deploy.backend.yml # backend + workers
config/deploy.feed.yml # custom feed service
The web deploy has Caddy serving the built frontend and host-mounted pre-rendered HTML releases. Backend deployment covers the API and workers. Feed has its own image and service.
Still the same idea: Docker images, Kamal configs, one server, explicit roles.
The deploy script detects changed areas and deploys the right targets:
scripts/push-and-deploy.sh
scripts/push-and-deploy.sh --force
kamal deploy --roles=web
kamal deploy -c config/deploy.backend.yml
kamal deploy -c config/deploy.feed.yml
It also handles a practical rule I care about: push to GitHub after deploy succeeds. If production deploy fails, origin/main should not advance as if everything shipped.
That rule matters more once agents are allowed to deploy. If production deploy fails, I want the repo state to say that clearly too.
Coding agents are good at text, diffs, commands, and logs. Kamal gives them exactly that.
A deployment problem usually becomes one of these:
.kamal/secrets or config/deploy.ymlAn agent can inspect those repo problems.
My project AGENTS.md files tell agents how to deploy, which package manager to use, how long web builds usually take, what not to print, and when to run the deploy in tmux with a callback.
That last part is important because deploys are long-running enough to be annoying inside a chat turn. The TheBlue instructions say web deploys have taken about 6.7 minutes, and that Vite can sit quietly at rendering chunks... for several minutes. The point of writing that down is to stop an agent from killing a deploy just because nothing printed for a while.
I want the agent to know that before it touches the system.
One server is simple, but RAM is finite.
If I have three coding agents working on three products, I do not want all three running Kamal deploys against the same server at the same time.
Agent Control handles that with a shared deploy lock:
deploy:hetzner-main
The rule is: acquire the lock before starting a Hetzner/Kamal deploy, keep it through verification, then release it. If another session already has it, the new deploy waits.
The actual workflow is still the normal project deploy. The lock wraps it.
Each repo still owns its deploy command. Agent Control serializes access to the shared server.
So the flow becomes:
agent finishes change
agent runs checks
agent commits
agent asks for deploy lock
Agent Control queues it if another deploy is running
agent deploys in tmux when lock is acquired
agent verifies production
agent releases lock
agent reports back
This is the part that makes one server work with agent-driven development. The server stays simple, but the deployment jobs are serialized.
One server has limits.
If the server is down, multiple products are affected. More capacity means moving pieces around. A product that grows a lot may need to leave the shared setup.
That is fine for where these products are now.
Most small products do not need a platform on day one. They need backups, logs, health checks, repeatable deploys, and a setup the owner understands. My setup has those pieces without making me operate a deployment platform.
Kamal is not magic. It still uses Docker, SSH, a registry, env files, health checks, and a proxy. The useful part is that those pieces are explicit and close to the code.
That fits my work better than a sprawling platform.
The pattern I keep copying into newer projects:
web, backend, feed, or worker roles instead of one giant container.kamal/secrets reading from .env.kamal, without committing valuesAGENTS.md deploy notesdeploy:hetzner-main for shared-server deploy serializationFor my current small-products life, this is enough infrastructure.
I can tell a coding agent to fix something, run the checks, deploy it, verify it, and report back. The deploy path is plain text the agent can read and reason about.
]]>One agent fixing a bug is easy. Five agents across different projects, with deploys, SEO checks, product loops, callbacks, and follow-up work, is a different problem. Once I run enough agents, I spend more time tracking sessions, queues, callbacks, and follow-ups than asking whether the agent can write code.
I built Agent Control for that layer of the work.
Agent Control is my in-house macOS app and CLI for coordinating coding-agent sessions. It does not replace Claude Code, Codex, or Droid. It sits around them and handles the parts I kept tracking by hand once coding agents became part of the daily workflow: queues, callbacks, loops, handoffs, locks, session history, and cross-project messages.
I am a bootstrapped indie developer, and I choose to work across many small projects at the same time. Part of that is because I use SEO as an inbound channel. SEO takes time. A project may need months before I know whether the idea, keywords, product, and market are worth more effort.
That pushes me toward a workflow with many small active bets, not one large project that gets all my time.
I have a loose rule now: write prompts instead of TODOs that never get worked on.
A TODO in a notes file is a reminder. It may get done. It may sit there for six months. A prompt in Agent Control can become a queued session, a child worker, or the next loop run.
That matters because a lot of agent work starts as a half-formed thought:
Not all of that should run immediately. A few prompts should wait behind the active same-repo session. Others should run as fresh child sessions, resume an existing coordinator, or run later.
Before Agent Control, this became a mix of tmux windows, notes, shell history, Reminders.app links, and me remembering which agent was doing what. That worked for a while. Then I had enough loops and projects that the bookkeeping became its own job.
I usually work on my own projects on the main branch. I do not reach for git worktrees unless I have a specific reason.
Partly taste, partly risk management. Most of my projects are small enough that serialized work is simpler. I would rather have one agent finish, review, commit, deploy, and archive before another agent starts changing the same repo.
Agent Control follows that preference. If a repo already has an active session, same-repo work queues behind it. A queued task can still be explicit about what it wants:
agent-control-cli add \
--repo ~/p/theblue/theblue.social \
--prompt "Check the onboarding funnel and suggest one low-risk improvement."
That prompt is queued.
There are exceptions. Parent loop sessions can spawn child sessions. Read-only investigations can force-start. But the default is conservative: one repo, one active lane.
The queue also depends on sessions exiting when they are done.
I have an ask-to-exit skill for that. A worker can finish the job, report back, then ask to close itself. Once Agent Control sees that session exit and archives it, the app knows the same-repo lane is clear and can start the next queued task.
Serial queueing works better when the finished agent can give Agent Control a clear “this session is done” signal.
I do not want an agent to only answer a prompt.
I want it to run the command, read the output, make the next decision, and report back to the right place. If a deploy takes a few minutes, I do not want to babysit the terminal. I want the deploy to run in tmux and send a callback to the exact Agent Control session that started it:
agent-control-cli message \
--session "$AGENT_CONTROL_SESSION_ID" \
--prompt "Deploy finished. Verify and report status."
That small callback changed a lot of my workflow.
Without it, a long-running command finishes somewhere. Maybe I notice. Maybe I do not. With it, the agent gets pulled back into the work at the right time. It checks the result, fixes errors if needed, and tells me what happened.
Agent Control has a CLI for the same reason. The app is useful, but the CLI lets agents, scripts, tmux panes, and loop workers coordinate without me clicking around.
A lot of my work crosses repo boundaries now.
A product loop may inspect analytics for one app, update a landing page, queue a follow-up in the blog, and tell a coordinator session what happened. Deploys can finish in tmux and report back to the exact session that started them. Child workers can finish SEO checks and message the parent loop before they exit.
Plain tmux does not try to solve that. tmux keeps processes alive. Agent Control gives those processes an address.
An Agent Control session ID is not the same thing as a Claude Code, Codex, or Droid session ID. Agent Control owns its own session identity. That gives me a stable target for messages:
agent-control-cli message \
--session "197B1443-06E7-40F6-BC6E-13AA3BC20A73" \
--prompt "The child SEO check finished. Schedule the next run for tomorrow."
That can come from another agent, a shell script, a tmux callback, or a loop worker. It does not matter which backing agent is underneath.
Most of my coding-agent workflow started in tmux.
I wrote about using tmux with Claude Code because tmux gave me the primitives I needed:
I kept all of that.
Agent Control is not a replacement for tmux. My long-running dev servers, deploys, and shell processes still run there. The difference is that tmux is process coordination, while Agent Control is agent-session coordination.
That includes deploys. If a command may take a few minutes, I still run it in tmux so the output stays visible and the process survives the agent session. Agent Control handles the callback when the command finishes.
tmux tells me where the process is.
Agent Control answers:
This works well for me. tmux stays good at being tmux. Agent Control handles the layer above it.
Agent Control is a SwiftUI macOS app with a SQLite database behind it. The CLI writes into the same database and notifies the app.
The app manages sessions for:
Each session has a repo path, agent type, status, transcript, archive state, queue state, and enough metadata for the app and CLI to find it again later.
The main things I use every day:
The UI is mostly there so I can see what is going on. The CLI is there so agent sessions running inside the Agent Control app can do the coordination themselves.
Session history matters more than I expected. When a session finishes something worth remembering, I can have it create a bookmark URL for the relevant point in the transcript and append that URL to my task log. Later, when I see the task in wip.md, I can jump back to the exact session history instead of searching through dozens of old agent conversations.
The CLI is intentionally small. I use it myself sometimes, but the main caller is usually an agent session already running inside the Agent Control macOS app.
Start a new task:
agent-control-cli add \
--repo ~/p/myog/myog.social \
--prompt "Check today's Google Search Console changes and report anything worth acting on."
Message an existing session:
agent-control-cli message \
--session "SESSION_ID" \
--prompt "The export finished. Verify the report and summarize the result."
Queue a child session under a parent:
agent-control-cli add \
--parent-session "$AGENT_CONTROL_SESSION_ID" \
--prompt "Run this loop iteration, then report back to the parent session."
Schedule the next loop run:
agent-control-cli loops schedule \
--session "SESSION_ID" \
--loop "LOOP_ID" \
--title "SEO check" \
--next-run "2026-07-05T09:00:00+08:00" \
--cadence "tomorrow" \
--prompt "$next_prompt"
The commands are plain enough for the agent to run. I can put them in AGENTS.md. A tmux deploy can call them after a long-running command finishes.
The loop workflow is where Agent Control became much more useful than my older Reminders.app setup.
The pattern uses two sessions:
The coordinator wakes up, creates a child worker, and waits. That child does the actual work, sends a structured callback to the coordinator, then exits or archives. After the callback arrives, the coordinator schedules the next run.
For example, an SEO loop may do this:
agent-control-cli messageThe long-lived loop context stays separate from the worker context. The coordinator does not need every log line from the child. It needs the result, evidence, changed files, commit, deploy status, blockers, and next action.
That one pattern cleaned up a lot of recurring work.
Agent Control does not replace repo instructions or skills.
I still use AGENTS.md to tell agents how to work inside a repo: commands, deploy rules, coding conventions, browser-check rules, and project-specific traps.
I still use skills for repeatable workflows: commit, deploy, take over, loop-task, external service reports, and so on.
Agent Control decides which session gets work and how sessions report back. AGENTS.md tells the agent how to do the work once it is in the repo. Skills package up workflows the agent should follow.
Those layers should stay separate. It’s easier to maintain.
Agent Control is not an IDE.
I did not add editing or git functionality to it. I already have Neovim and GitUp for those jobs. Agent Control has configurable commands to open the current file in my editor or the current repo in my git client, but it does not try to become either tool.
It is not a replacement for Claude Code, Codex, Droid, tmux, git, Kamal, DevSnoop, or AGENTS.md.
It does not make agents smarter, decide whether an SEO edit is good, remove review, or make five agents safely edit the same repo at once.
It mostly gives my agent work a place to go:
I do not need much more than that for my current workflow.
I built it by using it.
I did not start with a product spec. I started with places where the workflow kept breaking down:
I could have kept layering scripts on top of tmux. I still use plenty of scripts. But once session state, queue state, loop state, and callbacks all needed to agree, a small app with a database made more sense.
The full setup is still simple in the way I care about. Agent Control owns the state. The CLI exposes it. Agents use the CLI. tmux keeps the long-running processes visible.
]]>I do not think vibe-coded SaaS apps are automatically doomed. The problem is who is driving the agent.
The code can be bad even when each file looks plausible. The UI works, the demo looks real, and there are routes, components, migrations, and auth screens.
Then you look across the app:
AI is good at continuing a pattern. It is much worse when there is no pattern yet, or when the person driving it cannot tell whether the pattern is any good.
My workflow is built around avoiding that. For larger features, I write a spec first: data model, API behavior, edge cases, and what not to change. I wrote about this in Two Ways to Direct Coding Agents. For new projects, I often point the agent at one of my existing projects and tell it to build the same way, except for the parts I want changed.
Every repo I work on has an AGENTS.md file: commands, architecture, conventions, deployment rules, and mistakes the agent has made before.
I also have a simple skill that uses a second agent to review the first agent’s work. One writes the change, another reviews the dirty diff, then the first one fixes what the reviewer caught.
I would not automatically throw away every AI-built app. Plenty are fine. Others need hardening. A few should be rebuilt because the foundation is wrong.
The first pass I would do on a vibe-coded SaaS app is not a refactor. It is an audit:
role, plan, or owner IDs?When I use an agent for this, I avoid broad prompts like “is this app secure?” I ask it to check all API routes for authentication, authorization, ownership, server-owned fields, paid feature limits, rate limits, and secrets crossing into the frontend.
After that, the decision is clearer: patch, harden, or rebuild.
]]>localhost, add a forwarding URL when a provider needed to call back, update a dashboard, test the thing, then undo half of it later.
Cloudflare Tunnel changed that for me. My local apps now have stable HTTPS dev domains, so OAuth callbacks, webhooks, mobile callbacks, and browser testing go through the same public boundary every time.
Before tunnels, local testing looked like this:
browser -> http://localhost:5173
backend -> http://localhost:4000
provider dashboard -> random forwarding URL, if I remembered to update it
phone -> maybe my LAN IP, maybe nothing
That works for testing screens. It is awkward for integrations because the other service is not on my laptop.
Now I try to make local development look like a small public deployment:
browser
-> https://dev-example.com
-> Cloudflare Tunnel
-> http://localhost:5173
Stripe or GitHub
-> https://dev-example-backend.com/webhooks/provider
-> Cloudflare Tunnel
-> http://localhost:4000/webhooks/provider
phone
-> https://dev-example.com
-> Cloudflare Tunnel
-> http://localhost:5173
It is still local. The processes are still on my machine. But the URLs look like real URLs, with HTTPS, stable hostnames, and provider dashboards that do not need to change every time I restart a terminal.
Cloudflare has Quick Tunnels for development. You can run:
cloudflared tunnel --url http://localhost:8080
It prints a random trycloudflare.com hostname and proxies requests back to your local server. Cloudflare describes quick tunnels as useful for testing and development. I would not put a production site behind one.
I like quick tunnels for one-off sharing. I do not like them for normal product development.
Provider dashboards, OAuth clients, and mobile apps all remember URLs. If the hostname changes, the test setup changes.
For my own projects I use a named tunnel with hostnames I control. The Cloudflare setup is a little more work once, then the same URLs keep working:
cloudflared tunnel create dev
cloudflared tunnel route dns dev dev-example.com
cloudflared tunnel route dns dev dev-example-backend.com
Cloudflare documents that a tunnel gets a UUID-backed cfargotunnel.com target, and DNS records point your hostname at that tunnel target. The CLI route command creates the CNAME for locally-managed tunnels.
After that, my provider dashboard can keep using:
https://dev-example-backend.com/webhooks/stripe
https://dev-example-backend.com/oauth/google/callback
No random URL pasted into five places. No “which tunnel URL is current?” problem.
My ~/.cloudflared/config.yml is the map:
tunnel: <tunnel-id>
credentials-file: /Users/me/.cloudflared/<tunnel-id>.json
ingress:
- hostname: dev-example.com
service: http://localhost:5173
- hostname: dev-example-backend.com
service: http://localhost:4000
- service: http_status:404
Cloudflare’s configuration docs say ingress rules are matched from top to bottom, and configs with ingress rules need a final catch-all rule. I use http_status:404 because unmatched hostnames should fail clearly.
This file answers the question I used to keep in my head:
public hostname -> local port
When an integration breaks, I start with that mapping. I do not start in the provider dashboard.
When a callback or webhook fails, I check the path from outside in.
First, DNS:
dig +short dev-example-backend.com
Then HTTPS reachability:
curl -i https://dev-example-backend.com/health
Then the actual route:
curl -i \
-X POST \
-H 'Content-Type: application/json' \
--data '{"ping":true}' \
https://dev-example-backend.com/webhooks/provider
For webhook endpoints, I do not care if the fake request returns 400, 401, or signature verification failure. I care that the request reaches the local process and the log shows the route I expected.
Then I ask Cloudflare which ingress rule it would use:
cloudflared tunnel ingress rule https://dev-example-backend.com/webhooks/provider
And I validate the config:
cloudflared tunnel ingress validate
Those two commands are more useful than staring at dashboard settings. One tells me which rule matches the URL. The other catches config mistakes before I blame Stripe, GitHub, Google, or my app.
This also changed how I debug app config.
Many local bugs only show up when the app uses a public origin:
redirect_uri_mismatch.If I test everything on raw localhost, I can accidentally test a different app than the one I configured.
With tunneled dev domains, I can set local env vars to the same kind of values I use elsewhere:
APP_URL=https://dev-example.com
API_URL=https://dev-example-backend.com
GOOGLE_REDIRECT_URI=https://dev-example-backend.com/oauth/google/callback
STRIPE_WEBHOOK_URL=https://dev-example-backend.com/webhooks/stripe
The values are still development values. But they have the same scheme, hostname behavior, and callback path behavior as the deployed app.
That catches more useful bugs.
I still use localhost as the tunnel target. I avoid using it as the app URL once I settle on a domain name.
The local process still runs on a port:
http://localhost:5173
But I open the app through the tunnel subdomain:
https://dev-example.com
I usually put the project domain name into the tunnel subdomain. If the product is example.com, the local URLs become something like:
https://dev-example.com
https://dev-example-backend.com
That keeps the browser, backend config, OAuth callback URLs, webhook endpoints, cookies, and mobile testing on the same dev origin. I do not have one path through localhost and another path through the domain.
My rule is:
The tunnel config still points to localhost. I just stop treating localhost as the URL I develop against.
Before, an integration failure felt spread across too many places: local server, forwarding tool, provider dashboard, callback config, browser console, phone, and logs.
Now I start with the public route:
Only after that do I debug provider-specific behavior: signatures, event types, OAuth scopes, redirect URI registration, retries, and handler code.
I wrote the setup steps in Configuring Cloudflare Tunnel to Expose Servers for Local Development, Webhooks etc. Later I wrote about treating ~/.cloudflared/config.yml as my local dev directory.
This is the reason behind both posts: stable HTTPS dev domains make local integrations feel less like a pile of exceptions.
]]>Webhooks are different. Stripe or GitHub starts the request, and localhost means their machine, not mine. A localhost webhook URL will never reach my laptop from Stripe.
For local testing, I need a public URL that eventually reaches the process on my laptop.
A normal local request looks like this:
browser on my laptop -> http://localhost:3000/api/thing
A webhook delivery looks like this:
provider's server -> https://my-public-url.example.com/webhooks/provider
When I test webhooks locally, I want the provider’s server to hit a public HTTPS URL that forwards to my laptop:
provider's server
-> https://dev-my-app.example.com/webhooks/provider
-> tunnel
-> http://localhost:3000/webhooks/provider
Without the public URL, the provider has nowhere to send the request.
So I start by checking everything before the handler:
POST200, but your async work failed after thatIf any of those are wrong, I fix that before reading the handler code.
Before touching provider settings, I check the public URL from outside my app.
curl -i https://dev-my-app.example.com/webhooks/stripe
For a webhook endpoint, GET might return 404 or 405. That’s fine. I only care that the hostname resolves, TLS works, and the request reaches my app.
Then I send a fake POST:
curl -i \
-X POST \
-H 'Content-Type: application/json' \
--data '{"ping":true}' \
https://dev-my-app.example.com/webhooks/stripe
If this never appears in my local logs, I stop there and fix the tunnel, hostname, port, or route before touching provider settings.
For my own projects I usually use Cloudflare Tunnel with a stable dev subdomain. Cloudflare’s docs also show quick tunnels for development, which give you a public trycloudflare.com hostname.
I use a named tunnel with my own dev hostname because provider dashboards remember URLs, and random URLs turn local testing into dashboard bookkeeping.
I open the provider dashboard after I know my URL reaches my local server.
I want this order:
curl reaches the public URLWhen I skip that order, I waste time reading provider delivery logs for a URL my laptop never received.
A tiny temporary log helps:
app.post("/webhooks/stripe", express.raw({ type: "*/*" }), (req, res) => {
console.log("stripe webhook", {
method: req.method,
path: req.path,
contentType: req.header("content-type"),
stripeSignature: Boolean(req.header("stripe-signature")),
bytes: req.body.length,
});
res.sendStatus(200);
});
I keep that log noisy while wiring things up. Once requests arrive reliably, I cut it back.
Most webhook providers sign the raw request body.
Most signature failures I see locally come from losing those original bytes.
Stripe’s docs are explicit: signature verification needs the raw body, the Stripe-Signature header, and the endpoint secret. GitHub signs deliveries with X-Hub-Signature-256 when you configure a secret. Shopify signs HTTPS deliveries with X-Shopify-Hmac-SHA256 generated from the raw request body.
If your framework parses JSON before your webhook code runs, the bytes you verify may no longer be the bytes the provider signed.
In Express, this is the usual mistake:
app.use(express.json());
app.post("/webhooks/stripe", (req, res) => {
// req.body is already parsed.
// Stripe signature verification can fail here.
});
Use a raw body parser for the webhook route:
app.post(
"/webhooks/stripe",
express.raw({ type: "application/json" }),
(req, res) => {
const signature = req.header("stripe-signature");
const event = stripe.webhooks.constructEvent(
req.body,
signature,
process.env.STRIPE_WEBHOOK_SECRET!,
);
console.log("received", event.type);
res.sendStatus(200);
},
);
app.use(express.json());
In Express, put the webhook route before app.use(express.json()). In other frameworks, use whatever hook gives the handler the raw request body.
The same rule applies outside Express. Before verifying the signature, get the original request body in the exact form the provider expects.
I always check which endpoint created the secret.
Stripe is the easiest place to see this. A local stripe listen session gives you a signing secret for that forwarding session. A webhook endpoint created in the Stripe dashboard has its own signing secret. If I use the dashboard endpoint secret while testing stripe listen, signature verification fails.
Same practical rule for other providers: check which endpoint generated the secret.
My .env usually makes that explicit:
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_from_the_current_endpoint
Not:
WEBHOOK_SECRET=some_secret_i_found_somewhere
I name it after the provider and endpoint so I don’t grab the wrong secret later.
I keep browser debugging separate from webhook debugging.
For a browser call, I look at CORS, cookies, origins, preflight requests, and frontend dev servers.
A webhook delivery is server-to-server. The provider’s server sends an HTTP request to your endpoint. There is no browser enforcing CORS on that delivery.
CORS can still show up if you build a local admin page that calls your webhook route from the browser. In that case, your browser is calling your route. Stripe, GitHub, and Shopify are not delivering a webhook.
I separate the two tests:
# Webhook-style server request
curl -i -X POST https://dev-my-app.example.com/webhooks/provider
and:
browser app -> backend API
I don’t debug those with the same checklist.
A webhook handler should usually do three things synchronously:
Then a job or background worker does the real work.
If my handler sends email, calls three APIs, writes five records, and then returns 200, every local test has too many places to fail.
I prefer a small local first pass:
app.post("/webhooks/stripe", rawBody, async (req, res) => {
const event = verifyStripeEvent(req);
await db.webhookEvent.upsert({
where: { provider_event_id: event.id },
create: {
provider: "stripe",
provider_event_id: event.id,
type: event.type,
payload: event,
},
update: {},
});
res.sendStatus(200);
queue.enqueue("process-stripe-event", { eventID: event.id });
});
In my apps, the handler acknowledges receipt after verification and durable storage, then processes separately.
Local testing often hides this because you click “send test webhook” once and watch one request.
In production, Stripe can retry failed deliveries, GitHub lets me replay recent deliveries, and related events can arrive in a different order from the one I expected.
Stripe documents duplicate events and says not to depend on event ordering. Shopify includes a delivery ID you can use to detect duplicates. GitHub has delivery IDs and replay tooling in its webhook UI.
My table usually has at least:
provider
provider_event_id
event_type
received_at
processed_at
status
payload
For GitHub, the provider event ID might be the delivery ID. For Stripe, it is usually the event object’s id. Save the ID you need to make processing idempotent.
If I receive the same event twice, the second request should not create a second subscription, send a second welcome email, or mark an order twice.
When a local webhook fails, I go through this list in order:
3xx responses, old random tunnel URLs, and staging vs local domains.POST? Providers won’t call your nice browser-only GET route.2xx quickly? 3xx, 4xx, 5xx, and timeouts are failures for most providers.When I follow that order, I usually find the bad assumption quickly.
The local setup I use:
.envAt that point, the work is normal backend code: receive the request, verify it, store the event, process it, and make it safe to run twice.
I fix reachability first, then the handler.
]]>That sounds obvious until you are staring at a request that works in curl, fails in fetch, and gives you a console error that reads like the browser is being difficult. Most of the time, the browser is enforcing a security rule your server, iframe, cookie, or local dev setup did not account for.
The useful mental model is simple: the web platform protects users by making some things fail at the browser boundary. Your job is to find which boundary you hit before changing app code.
I split these failures into two buckets:
A request that never reached the server needs a different fix from a response your JavaScript was not allowed to read.
This is the first pass I use in DevTools:
200, 204, 302, 401, or something else?Origin, Cookie, Authorization, Access-Control-Request-Method, and Access-Control-Request-Headers.Access-Control-Allow-Origin, Access-Control-Allow-Credentials, Set-Cookie, Content-Security-Policy, Permissions-Policy, Cross-Origin-Opener-Policy, and Cross-Origin-Embedder-Policy.The console is good at telling you the rule name. The Network tab is better at telling you what happened.
I wrote a separate post on not fixing CORS by disabling CORS. The same debugging rule applies here.
CORS is a browser-enforced read permission for cross-origin responses. It does not protect your API from curl, backend jobs, CLI scripts, or attackers who call the API directly. It controls whether JavaScript running on one origin can read a response from another origin.
MDN’s Origin docs define an origin as the scheme, hostname, and port. A different port or scheme gives you a different origin:
http://localhost:5173
http://localhost:5174
https://localhost:5173
https://app.example.com
https://www.example.com
A request like this can fail even when the endpoint exists:
await fetch("https://api.example.com/projects", {
method: "POST",
headers: {
"content-type": "application/json",
authorization: `Bearer ${token}`,
},
body: JSON.stringify({ name: "Demo" }),
});
That request usually triggers a CORS preflight because it is cross-origin and uses headers/methods outside the simple request path. The browser first sends an OPTIONS request asking whether the real request is allowed.
You can reproduce the preflight:
curl -i -X OPTIONS 'https://api.example.com/projects' \
-H 'Origin: https://app.example.com' \
-H 'Access-Control-Request-Method: POST' \
-H 'Access-Control-Request-Headers: content-type, authorization'
The response needs to answer that request:
HTTP/2 204
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET,POST,OPTIONS
Access-Control-Allow-Headers: content-type,authorization
Vary: Origin
If cookies are involved, wildcard origins are out:
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
That combination does not work for credentialed browser requests. MDN’s Access-Control-Allow-Credentials docs cover the credential side of this. Return the exact allowed origin and include the Vary response header with Origin.
The diagnostic rule: if it works in curl and fails in the browser, check the browser contract, not just the API handler.
Cookie bugs are good at looking like auth bugs.
You log in. The response has Set-Cookie. The next API request still looks logged out. It is tempting to debug the session store first. Sometimes the browser rejected the cookie, stored it under a different site context, or decided not to send it.
Check the cookie in DevTools:
Set-Cookie response accepted?Path too narrow?Secure present for HTTPS-only cookies?HttpOnly present if JavaScript should not read it?SameSite right for the navigation or embedded flow?For cross-site cookies, the practical default is:
Set-Cookie: session=abc; Path=/; HttpOnly; Secure; SameSite=None
SameSite=None requires Secure in modern browsers. Cookies without a SameSite attribute are commonly treated as Lax, which means they may not be sent in the embedded or cross-site request you expected. MDN’s Set-Cookie page is the one I check when I forget the exact attribute behavior.
Also check the frontend call:
await fetch("https://api.example.com/me", {
credentials: "include",
});
If credentials is missing, fetch will not include cookies on cross-origin requests. If credentials is present but your CORS response does not allow credentials, JavaScript still cannot use the response.
The diagnostic rule: inspect the cookie storage and the request’s Cookie header. Do not infer cookie behavior from the login response alone.
Mixed content is another “but the URL works when I open it” trap.
An HTTPS page loading http:// scripts, stylesheets, fonts, iframes, or API calls is not the same as opening that HTTP URL in a tab. The page is secure; the subresource is not. The browser may upgrade the request to HTTPS or block it, depending on the resource type and browser behavior. MDN’s mixed content docs describe the current upgradable/blockable split.
This often appears after moving a site behind HTTPS:
<script src="http://cdn.example.com/widget.js"></script>
<img src="http://images.example.com/logo.png" />
Fix the URLs at the source:
<script src="https://cdn.example.com/widget.js"></script>
<img src="https://images.example.com/logo.png" />
Do not paper over this by telling people to allow insecure content in the browser. That only hides the production problem.
The diagnostic rule: search the generated HTML and runtime config for http://, not just source files.
curl -s https://app.example.com | rg 'http://'
For built frontend apps, also inspect generated assets:
rg 'http://' dist .next build public
Content Security Policy is one of the most useful browser security features and one of the easiest to mistake for random breakage.
You add an analytics script, payment widget, image CDN, iframe, or inline script. The browser blocks it. The app code did not change much, but the page has a policy that says which sources are allowed.
Example:
Content-Security-Policy: default-src 'self'; script-src 'self'; img-src 'self' data:
This policy says scripts must come from the same origin. A third-party script will be blocked:
<script src="https://analytics.example.com/script.js"></script>
Keep CSP enabled and add the narrow source you need:
Content-Security-Policy: default-src 'self'; script-src 'self' https://analytics.example.com; img-src 'self' data:
For inline scripts, prefer a nonce or hash. Do not add 'unsafe-inline' unless you have decided the tradeoff explicitly.
CSP has a good test mode:
Content-Security-Policy-Report-Only: default-src 'self'; script-src 'self'
That reports violations without enforcing the policy. I use Content-Security-Policy-Report-Only when tightening a real app because it tells me what would break before I break it.
The diagnostic rule: when the console says “Refused to load”, read the effective directive and the blocked URL. CSP errors usually include both.
Iframe failures often look like the child app is broken. Sometimes the parent page did not grant the feature.
There are two common places to check.
First, the iframe’s allow attribute:
<iframe
src="https://checkout.example.com"
allow="camera; microphone; payment"
></iframe>
Second, the page’s Permissions-Policy header:
Permissions-Policy: camera=(), microphone=(), geolocation=()
That header can disable browser features for the document and nested browsing contexts. If the parent denies camera access, the embedded page cannot fix that by calling getUserMedia() harder.
The same pattern shows up with sandboxed iframes:
<iframe
src="https://tool.example.com"
sandbox="allow-scripts allow-forms"
></iframe>
Without the right sandbox tokens, navigation, popups, forms, scripts, or same-origin behavior may be restricted. Sandboxing intentionally removes capabilities until the parent page grants them back.
The diagnostic rule: debug the parent page and iframe attributes before changing the embedded app.
Cross-origin isolation is useful for powerful APIs such as SharedArrayBuffer, but the headers are strict. Google’s COOP/COEP explainer is still a useful overview when you need the practical consequence rather than only the header syntax.
The usual set looks like this:
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
COOP can separate your top-level page from cross-origin popups. COEP can require embedded cross-origin resources to explicitly opt in with CORS or Cross-Origin-Resource-Policy.
That means a third-party script, worker, image, or wasm file that loaded before may stop loading after you enable isolation. The browser is not confused. You asked it to isolate the page.
Check this in the console:
window.crossOriginIsolated
If it is false, inspect the blocked resource. If it is true and popups or embeds changed behavior, inspect the COOP/COEP headers on the top-level page and the resource headers on the things it embeds.
The diagnostic rule: when you enable isolation, audit every cross-origin script, worker, iframe, and binary resource.
When a browser feature looks like a bug, I use this order:
curl, but do not treat curl as proof that browser code should work.http:// URLs, and old environment values.fetch call.Here is the small test page I reach for when I want to remove framework noise:
<!doctype html>
<meta charset="utf-8" />
<button id="run">Run request</button>
<pre id="out"></pre>
<script>
document.querySelector("#run").addEventListener("click", async () => {
const out = document.querySelector("#out");
try {
const response = await fetch("https://api.example.com/me", {
credentials: "include",
headers: {
"content-type": "application/json",
},
});
out.textContent = `${response.status}\n${await response.text()}`;
} catch (error) {
out.textContent = String(error);
console.error(error);
}
});
</script>
Serve it from the same origin as your app or from the origin you are testing:
python3 -m http.server 5173
Then compare the exact Origin header, preflight, cookies, and response headers with your real app.
These failures feel inconsistent because different browser APIs have different defaults:
The common thread is not “browser weirdness”. It is policy enforcement at the browser boundary.
Once I look for the policy first, the bug usually gets smaller.
]]>The usual fix I see is some version of “disable CORS”, “allow all origins”, or “install a browser extension”. That might get the request through in development, but it also hides the actual problem: the browser asked your server whether this frontend is allowed to read the response, and your server answered badly.
Fix it by making the browser, frontend, and backend agree on the request.
CORS is a browser-enforced HTTP contract.
Your frontend says:
Origin: https://app.example.com
Your backend says:
Access-Control-Allow-Origin: https://app.example.com
If those line up, the browser lets your JavaScript read the response. If they do not, the browser blocks your JavaScript from reading it.
CORS controls browser access to responses. API authentication is a separate layer. It does not stop curl, another backend, a CLI script, or someone calling your API directly. It controls whether browser JavaScript from another origin can read the response. MDN’s CORS guide puts it in the same terms: browsers restrict script-initiated cross-origin requests unless the response includes the right CORS headers.
An origin is not “the domain”. It is:
All of these are different origins:
http://localhost:5173
http://localhost:5174
https://localhost:5173
https://app.example.com
https://www.example.com
If your Vite app runs on http://localhost:5173 and your API allows http://localhost:3000, CORS is working correctly when the browser blocks it.
Open DevTools and click the failing request.
I check these fields before touching server code:
GET, POST, OPTIONS, etc.authorization, content-type, and custom x-* headersaccess-control-allow-origin, access-control-allow-credentials, access-control-allow-methods, access-control-allow-headersOPTIONS requestDo not debug CORS from the console message alone. The console usually tells you the symptom. The Network tab tells you what the browser sent and what the server answered.
When the browser sends a non-simple request, it may send an OPTIONS preflight first. The preflight asks the server whether the real request is allowed.
I usually reproduce it like this:
curl -i -X OPTIONS 'https://api.example.com/projects' \
-H 'Origin: https://app.example.com' \
-H 'Access-Control-Request-Method: POST' \
-H 'Access-Control-Request-Headers: content-type, authorization'
A useful response looks like:
HTTP/2 204
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET,POST,OPTIONS
Access-Control-Allow-Headers: content-type,authorization
Vary: Origin
If the browser request uses cookies or HTTP auth, it also needs:
Access-Control-Allow-Credentials: true
And the frontend request must opt in:
await fetch("https://api.example.com/projects", {
method: "POST",
credentials: "include",
headers: {
"content-type": "application/json",
},
body: JSON.stringify({ name: "New project" }),
});
If your API uses bearer tokens in the Authorization header, that header still has to be allowed in the preflight:
Access-Control-Allow-Headers: content-type,authorization
This does not work for credentialed browser requests:
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
The Fetch standard is explicit here: when the request’s credentials mode is include, Access-Control-Allow-Origin cannot be *. MDN says the same thing for Access-Control-Allow-Origin: wildcard is for requests without credentials.
If cookies are involved, return the exact origin:
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Credentials: true
Vary: Origin
Also check your cookie settings. Cross-site cookies usually need:
Set-Cookie: session=...; Path=/; HttpOnly; Secure; SameSite=None
If you are testing on plain http://localhost, Secure cookies are another thing to check. The browser may reject or omit the cookie before your API code is even involved.
This is the pattern I use:
const allowedOrigins = new Set([
"https://app.example.com",
"https://admin.example.com",
"http://localhost:5173",
]);
app.addHook("onRequest", async (request, reply) => {
const origin = request.headers.origin;
if (origin && allowedOrigins.has(origin)) {
reply.header("Access-Control-Allow-Origin", origin);
reply.header("Vary", "Origin");
reply.header("Access-Control-Allow-Credentials", "true");
}
if (request.method === "OPTIONS") {
reply.header("Access-Control-Allow-Methods", "GET,POST,PUT,DELETE,OPTIONS");
reply.header("Access-Control-Allow-Headers", "content-type,authorization");
return reply.status(204).send();
}
});
I care more about the allowlist check than the framework code:
allowedOrigins.has(origin)
Do not do this:
reply.header("Access-Control-Allow-Origin", request.headers.origin);
reply.header("Access-Control-Allow-Credentials", "true");
That reflects any website that asks. If your API uses cookies, you just told the browser that any origin can read credentialed responses from your API.
OWASP’s CORS testing guide describes the same thing from the security side: the browser sends Origin, and the server uses CORS headers to decide whether that cross-origin request is allowed. Make an actual allow/deny decision before reflecting the origin.
If you use Fastify, @fastify/cors already has the pieces:
import cors from "@fastify/cors";
const allowedOrigins = new Set([
"https://app.example.com",
"https://admin.example.com",
"http://localhost:5173",
]);
await fastify.register(cors, {
origin(origin, callback) {
if (!origin) {
callback(null, false);
return;
}
callback(null, allowedOrigins.has(origin));
},
credentials: true,
methods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
allowedHeaders: ["content-type", "authorization"],
});
The Fastify CORS plugin supports booleans, strings, regexes, arrays, and custom functions for origin. I prefer the function for production apps because it makes the allowlist explicit and easy to log.
I treat these as different checks:
Debug them separately.
If curl works but the browser fails, that usually means the API is reachable and the CORS contract is wrong.
If the preflight fails with 404, 405, or a 3xx response, your server or proxy probably is not handling OPTIONS on that route.
If the preflight succeeds but the real request fails, compare the real response headers. I have seen APIs add CORS headers to 204 preflight responses but not to 401, 403, or 500 responses. The browser still needs CORS headers on the response it is trying to expose.
If the request succeeds without cookies but fails after adding credentials: "include", check the exact Access-Control-Allow-Origin value first. A wildcard origin stops being valid for that request. After that, check whether Access-Control-Allow-Credentials: true is present and whether the browser sent the cookie.
If your local frontend is calling your local backend through public dev domains, use the actual dev domain origin in the allowlist. For local webhook and callback testing, I prefer my Cloudflare Tunnel setup because it keeps the browser origin close to production.
* is fineAccess-Control-Allow-Origin: * is fine for public, non-credentialed resources:
It is not fine as the default for an authenticated app API.
For SaaS apps, my default is:
Vary: Origin when returning the request originOPTIONS handled before auth middleware rejects itThat fixes the real problem. The browser stops complaining because the server is now saying exactly what it means.
Sources I checked while writing this: MDN’s CORS guide, MDN on Access-Control-Allow-Origin, the WHATWG Fetch standard’s CORS credential rules, OWASP’s CORS testing guide, and the @fastify/cors options.
I would not build on that mental model. Browser security mostly protects the user sitting in the browser. Your backend still has to protect itself from every client that can send HTTP.
The browser has real security rules.
Same-origin policy restricts how a script loaded from one origin can interact with resources from another origin.
CORS lets a server tell the browser which other origins should be allowed to read a response. For some cross-origin requests, the browser sends a preflight request first and checks whether the server allows the actual method and headers.
The browser enforces that rule.
Say your frontend at https://app.example.com runs a request like this.
await fetch("https://api.example.com/admin/users", {
method: "DELETE",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({ userID: "123" }),
})
the browser may block the frontend from reading the response unless the API sends the right CORS headers.
That does not mean the backend rejected the operation.
The request may still reach your server. For non-browser clients, CORS is not the gate at all:
curl -i -X DELETE "https://api.example.com/admin/users" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer stolen-or-low-privilege-token" \
--data '{"userID":"123"}'
curl, Postman, a script running on a VPS, and a compromised mobile app do not care that your React app would not show the button.
Frontend validation is useful. I want the form to catch a bad email before it hits the network. The upload picker should reject a 200 MB file immediately. Normal users should not see admin buttons.
But none of those checks should be the reason the backend accepts or rejects the request.
Keep the frontend check:
// frontend
if (file.size > 10 * 1024 * 1024) {
throw new Error("File is too large")
}
This still has to exist:
// backend
const maxUploadBytes = 10 * 1024 * 1024
if (uploadedFile.size > maxUploadBytes) {
return reply.status(413).send({ error: "File is too large" })
}
Same for plan limits:
// frontend
const canGenerate = currentUsage.generatedThisMonth < plan.monthlyGenerations
Enforce the same limit on the backend:
// backend
const usage = await getUsageForAccount(accountID)
const plan = await getPlanForAccount(accountID)
if (usage.generatedThisMonth >= plan.monthlyGenerations) {
return reply.status(402).send({ error: "Generation limit reached" })
}
The frontend makes the happy path nicer. The backend decides what is allowed.
When I review this class of bug, I start by copying requests out of DevTools and changing the values.
In Chrome or Safari:
curlThen I try the requests the UI is supposed to prevent:
# Can I update a server-owned field?
curl -i -X PATCH "https://api.example.com/me" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
--data '{"name":"Hwee-Boon","role":"admin","plan":"enterprise"}'
# Can I access another user's object?
curl -i "https://api.example.com/invoices/inv_other_user" \
-H "Authorization: Bearer $TOKEN"
# Can I run an expensive operation after the UI disables it?
for i in {1..20}; do
curl -s -X POST "https://api.example.com/generate" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
--data '{"prompt":"write me a long report"}' >/dev/null
done
Use whatever shell you use. Just stop testing only through the UI.
I want to see boring failures:
401 when the request is not authenticated403 when the user is authenticated but not allowed404 when the object should not be visible to that user413 when an upload is too large422 when the body has invalid client-controlled fields429 when the caller is over the rate limitIf changing a JSON field gives me admin access, a cheaper plan, another user’s data, or extra paid API calls, the backend is trusting the frontend.
CORS is often the part that confuses people because it looks like an access control system.
For example:
Access-Control-Allow-Origin: https://app.example.com
That header tells browsers whether frontend code from that app origin may read the response. It does not prove the caller is your app. It does not prove the user is allowed to perform the action.
Do not write code like this:
const origin = request.headers.origin
if (origin !== "https://app.example.com") {
return reply.status(403).send({ error: "Forbidden" })
}
await deleteProject(request.body.projectID)
That blocks some browser-based abuse. It is not enough.
Write the boring checks:
const user = await requireUser(request)
const project = await getProject(request.body.projectID)
if (!project || project.accountID !== user.accountID) {
return reply.status(404).send({ error: "Not found" })
}
if (user.role !== "admin") {
return reply.status(403).send({ error: "Forbidden" })
}
await deleteProject(project.id)
The exact framework does not matter. The rule does: authenticate the user, load the server-side record, check ownership and permissions, then do the work.
OWASP calls this Broken Object Level Authorization when APIs let callers access objects by changing IDs. It is still one of the easiest backend bugs to create because the happy path works perfectly.
The fastest way to create a backend bug is to accept the whole request body and pass it into your database update.
Avoid this:
await db.user.update({
where: { id: user.id },
data: request.body,
})
The UI may only send this:
{
"displayName": "Hwee-Boon"
}
but an attacker can send this:
{
"displayName": "Hwee-Boon",
"role": "admin",
"billingPlan": "enterprise",
"emailVerified": true
}
Use an allowlist:
const body = updateProfileSchema.parse(request.body)
await db.user.update({
where: { id: user.id },
data: {
displayName: body.displayName,
avatarURL: body.avatarURL,
},
})
This applies to reads too. Do not return a giant object and rely on the frontend to hide sensitive fields. Return the fields the current user is allowed to see.
OWASP’s Broken Object Property Level Authorization covers this kind of overexposure and mass assignment problem.
Cookies make this more subtle.
If your app uses cookie-based sessions, the browser may attach those cookies automatically when it sends a request to your site. Your app gets simpler. It is also why CSRF exists: another site can try to make the user’s browser send an unwanted request to your site while the user is logged in.
Same-origin policy and CORS are not a full CSRF defense. They mainly affect whether malicious frontend code can read responses or send certain request types. You still need backend protection for state-changing routes.
For cookie-authenticated apps, I usually want:
SameSite=Lax or stricter cookies unless the app genuinely needs cross-site cookiesOrigin or Referer checks as a backup signalGETDo not treat Origin as identity. Treat it as one CSRF signal for browser requests. A non-browser client can send its own Origin header.
Modern browsers also send fetch metadata headers such as Sec-Fetch-Site and Sec-Fetch-Mode in many requests. MDN notes that these are forbidden request headers, so frontend JavaScript cannot set them directly.
That makes them useful for rejecting suspicious browser-originated cross-site requests.
It does not turn them into authentication. A server-side script can still send whatever text it wants over HTTP. Your backend should use these headers as an extra browser-request filter, not as a replacement for auth, permissions, CSRF protection, and rate limits.
For each backend route, I want a clear answer to these:
This is the prompt I would give a coding agent:
Review the backend API routes for places where the backend trusts the frontend.
For each route, check:
- missing authentication
- missing authorization
- object IDs not scoped to the current user/account
- request body fields that can overwrite server-owned fields
- expensive operations without server-side limits
- cookie-authenticated state changes without CSRF protection
- CORS or Origin checks being used as the main security check
Return concrete file paths, route names, exploit examples, and proposed fixes.
Then I would ask it to write direct request tests for the risky routes. A Playwright test through the UI is not enough for this. I want tests that hit the backend route with bad payloads and prove the server rejects them.
The browser is useful. Users get a safer place to run untrusted web pages. Your app gets useful signals. Plenty of dumb mistakes get blocked.
It is not guarding your backend.
]]>The categories I use are simple:
Agents get worse when every tool is described as every other tool.
Slash commands are good for short, local interactions inside one agent.
Examples:
/review
/commit
/spec
/clear
They are convenient and fast. Usually they are tied to the agent you are using.
I do not use slash commands as the long-term place for detailed workflow knowledge. They are better as short triggers.
If /commit means “inspect dirty files, run formatters, choose an atomic commit message, avoid unrelated files, and use this repo’s commit style”, then the actual instructions belong somewhere more portable.
I put that in a skill.
A skill is a markdown file that tells the agent how to do a repeatable task.
I use skills for workflows like:
Each one needs more than a single shell command.
The agent has to inspect state, choose the right command, avoid certain files, handle errors, and report back. Skills work well for that.
A good skill says:
Use this when the user says "commit".
Steps:
- inspect `git status`
- review the diff
- run the smallest relevant checks
- stage only intended files
- commit with the repo's commit style
- report the commit hash
Guardrails:
- do not include unrelated user changes
- do not rewrite history
- do not commit secrets
That gives the agent a small operating procedure.
MCP is useful when the agent needs a structured interface to something outside the repo.
Good MCP uses:
I do not use MCP just to hold instructions.
If the task is “when deploying, use Kamal in tmux and add an Agent Control callback”, that belongs in AGENTS.md or a deploy skill.
If the task is “query production logs with a time range, service name, and structured filters”, MCP might make sense. The agent gets a tool with parameters instead of hand-assembling curl commands every time.
MCP also has prompts and resources. I still treat those as interfaces to a running server or external context, not as the place to keep my personal repo rules.
My rule: if the agent needs structured context or an action exposed by another system, use MCP. If the agent needs a procedure, use a skill.
Some workflows should be plain scripts.
If the steps are deterministic and do not need model judgment, I write a CLI script:
bun scripts/generate-sitemap.ts
bun scripts/check-links.ts
bun scripts/export-report.ts --from 2026-05-01 --to 2026-05-29
The agent can still run the script. I want the branching and edge cases in code.
I use this pattern for checks:
The script can fail loudly and consistently. The agent then fixes the failure.
That is better than asking the agent to remember every edge case from a paragraph.
Here is the decision table I use:
| Need | Use |
|---|---|
| Short trigger inside one agent | Slash command |
| Repeatable workflow with judgment | Skill |
| Structured external context or actions | MCP |
| Deterministic automation | CLI script |
| Standing repo rule | AGENTS.md |
Most workflows I care about use more than one.
For example, my deploy flow has:
AGENTS.md for the standing rule: deploys run in tmuxThe skill coordinates the work. Kamal does the deterministic deploy. Repo instructions keep the agent from guessing.
Commit looks like a slash command. In practice, I want more than git commit.
The easy version:
git add .
git commit -m "Update"
The version I want:
That is a skill.
The skill may still run normal CLI commands:
git status --short
git diff
git add path/to/file
git commit -m "Write"
The judgment around those commands is the useful part.
Log export is different.
Part of it is process:
Part of it is structured access:
That can start as a skill. If I run it often enough, the query part should become a script or MCP tool.
I do not need to decide upfront. I usually start with a skill because it captures what I learned while doing the task. Then I move deterministic parts into code.
Deployment uses the same split.
My deploy workflow has judgment:
That belongs in instructions and skills.
The actual deploy command is still a CLI:
kamal deploy
I want the agent to follow the project workflow: run the command, read the output, and know when to stop.
If the deploy is long-running, my repo instructions say to run it in tmux and send an Agent Control callback when it finishes. That rule lives in AGENTS.md because it applies across deploy tasks.
The skill can then focus on the sequence:
Kamal does the deployment. The skill handles the workflow around it.
I keep standing rules in AGENTS.md.
Examples:
pnpm for installsbun runThose rules should be loaded every session. They change how the agent behaves across the repo.
I do not put a full deploy runbook or log-export guide in AGENTS.md. That turns the file into a junk drawer.
The top-level file should route the agent:
- When I say "commit", use `commit-succinct`.
- When I say "deploy", use the project deploy skill.
- Better Stack log exports use the `betterstack-log-export` skill.
The detailed workflow goes in the skill. Deterministic work goes in code. Repo rules stay short.
When a skill grows a long checklist with no judgment, I usually turn that part into a script.
For example, this should be code:
The script gives the agent a pass/fail result.
That is better than a paragraph that says “make sure the sitemap is correct.” The agent can eyeball the file and miss a URL.
With a script:
bun run check:seo
The agent gets a real failure. Then it can fix the source and rerun the check.
I use the same pattern for content work.
The writing guidance belongs in a skill because it needs judgment. The mechanical checks belong in tools. For these posts, writing-voice gives the style rules, and prosesmasher catches repeated cadence, boilerplate, and article-structure problems.
Neither one replaces reading the draft. The skill tells the agent what good looks like. The checker catches things that are easy to miss when editing quickly.
That combination is better than telling the agent “make it sound human.” Give it the voice rules, run the checker, edit the file, and run the checker again.
The same pattern works for code too. I put taste and judgment in instructions, then put repeatable verification in commands. The agent has to use both before it says the work is ready to ship safely.
A SaaS starter kit should include a way to work on the code.
That means:
Stacknaut includes agent configuration because this is how I build production apps now. If you are starting from a blank repo, the AGENTS.md generator gives you a first draft before you split repeated workflows into skills.
The app code is not enough. The workflow around the app has to be there too.
Without it, every new agent session starts by guessing.
]]>That does not mean I want SSR.
For my use case, Vite static output plus prerendered HTML is enough: generate real HTML for public routes at build time, write the SEO tags into each page, and serve static files.
A plain Vite SPA usually ships one index.html:
<div id="app"></div>
<script type="module" src="/src/main.ts"></script>
Vue Router handles the route after JavaScript loads.
A plain SPA is fine for an app dashboard. It is not enough for public pages where I care about search previews, canonical URLs, and content being visible in the initial HTML.
For SEO pages, I want this in the static output:
<title>Kamal vs Coolify for Solo SaaS Deployment</title>
<meta name="description" content="A practical comparison of Kamal and Coolify..." />
<link rel="canonical" href="https://example.com/kamal-vs-coolify/" />
<meta property="og:title" content="Kamal vs Coolify for Solo SaaS Deployment" />
<meta property="og:description" content="A practical comparison of Kamal and Coolify..." />
<meta property="og:url" content="https://example.com/kamal-vs-coolify/" />
And I want the page body rendered too.
No need to make the server render every request if the content changes when I deploy anyway.
The first step is to stop scattering SEO data across components.
I keep public route metadata in a structured list:
export const publicPages = [
{
path: "/kamal-vs-coolify/",
title: "Kamal vs Coolify for Solo SaaS Deployment",
description:
"A practical comparison of Kamal and Coolify for solo SaaS apps.",
ogImage: "https://example.com/og/kamal-vs-coolify.png",
},
{
path: "/vue-prerendering-without-ssr/",
title: "Vue Prerendering Without SSR",
description:
"How to prerender Vue marketing pages at build time without moving to SSR.",
ogImage: "https://example.com/og/vue-prerendering.png",
},
] as const
Vue Router can use the same data:
export const routes = publicPages.map((page) => ({
path: page.path,
component: () => import("./pages/MarketingPage.vue"),
meta: {
title: page.title,
description: page.description,
ogImage: page.ogImage,
},
}))
The prerender script can use it too.
That avoids the usual mess where the browser title says one thing, the sitemap says another, and the generated HTML has an old description.
I usually keep this as a small build step after Vite builds the client bundle.
The rough flow:
bun run build
bun run prerender
The prerender script:
dist/index.htmldist/<route>/index.htmlsitemap.xmlThe meta tag replacement can stay boring:
function escapeHTML(value: string): string {
return value
.replaceAll("&", "&")
.replaceAll("<", "<")
.replaceAll(">", ">")
.replaceAll('"', """)
}
function withSeoTags(html: string, page: PublicPage): string {
const canonicalURL = new URL(page.path, "https://example.com").toString()
const title = escapeHTML(page.title)
const description = escapeHTML(page.description)
return html
.replace(/<title>.*?<\/title>/, `<title>${title}</title>`)
.replace(
/<meta name="description" content=".*?">/,
`<meta name="description" content="${description}">`,
)
.replace(
"</head>",
[
`<link rel="canonical" href="${canonicalURL}">`,
`<meta property="og:title" content="${title}">`,
`<meta property="og:description" content="${description}">`,
`<meta property="og:url" content="${canonicalURL}">`,
`<meta property="og:image" content="${page.ogImage}">`,
"</head>",
].join("\n"),
)
}
You can use an HTML parser if you want. The important part is simpler: every SEO route gets its own static HTML file.
It is tempting to set all of this from Vue Router:
router.afterEach((to) => {
document.title = String(to.meta.title)
})
I still do that for the running app. It is useful when users navigate between pages after JavaScript loads.
But it does not solve static SEO output. The generated HTML still needs the title and meta tags before the browser runs the app.
So I treat router metadata as input, not the whole solution. The prerender step writes the final tags into each index.html.
The browser can update the title later. Google can render JavaScript, but that still adds another step, and not every crawler or link preview bot runs JavaScript. I do not want the important tags to depend on that.
The easiest mistake is adding a new public route and forgetting to add it to the prerender list.
I like a small script that fails the build when a public SEO route is missing static output:
import { existsSync } from "node:fs"
import { join } from "node:path"
import { publicPages } from "../src/publicPages"
const missing = publicPages.filter((page) => {
return !existsSync(join("dist", page.path, "index.html"))
})
if (missing.length > 0) {
console.error(
missing.map((page) => `Missing prerender output: ${page.path}`).join("\n"),
)
process.exit(1)
}
Then the build flow becomes:
bun run build
bun run prerender
bun run check:prerender
The check is especially useful with coding agents. If the agent adds /compare/kamal-vs-coolify/ but forgets to include it in the prerender list, the script catches it.
I would rather have a boring build failure than discover the problem in Search Console two weeks later.
SPAs make it easy to accidentally serve the same content from multiple URLs:
/pricing/pricing//index.html/?route=pricingPick one.
I prefer trailing slashes for static routes because they map cleanly to directories:
dist/pricing/index.html
dist/kamal-vs-coolify/index.html
Then the canonical URL should match exactly:
<link rel="canonical" href="https://example.com/pricing/" />
The sitemap should use the same URL. Internal links should use the same URL. Do not make Google decide which version you meant.
For static marketing routes, the sitemap should come from the same page list:
const urls = publicPages.map((page) => {
const loc = new URL(page.path, "https://example.com").toString()
return `<url><loc>${loc}</loc></url>`
})
I do not want a second list of URLs just for sitemap.xml.
The practical rule:
publicPagespublicPages, it gets prerenderednoindex or keep it out<a href="..."> links, not hash routesThat keeps the SEO surface small enough to reason about.
Build-time prerendering works well for:
It is less useful for pages where the HTML needs to change per request:
For those, SSR or server-generated pages may be worth it.
Most SaaS marketing sites do not need that. They need stable public pages with good titles, descriptions, canonical URLs, and Open Graph previews.
Stacknaut uses Vue because I like the productivity of Vue for app work. I do not want to give up that app structure just because the marketing site needs SEO.
The setup I like:
I get static output that search engines and social previews can read, without running an SSR server or moving to another framework.
The weak spot is dynamic content.
If a page changes every few minutes, prerendering at deploy time is the wrong tool. You either need server-rendered HTML, a separate static regeneration job, or a page that is not trying to rank.
I also avoid prerendering anything that depends on auth state. A logged-in dashboard should not be in the sitemap. The HTML can be empty until the app loads because search traffic is not the point of that page.
That split keeps the architecture simple:
Most of my SaaS work fits that split.
I also keep the app shell separate from the marketing pages mentally. The app can have loading states, auth forwarding, and client-only data fetching. The marketing pages need stable text, stable URLs, and stable previews.
The two sides have different jobs. Trying to make one route mode handle everything is how a simple SPA turns into a half-SSR framework project by accident.
If I need that later, fine. I would rather start with static output and add server rendering only when a page proves it needs it.
The other place this can break is URL forwarding.
If /pricing forwards to /pricing/, make the canonical URL /pricing/ and put /pricing/ in the sitemap. Do not mix both forms across nav links, generated pages, and marketing copy.
I also like checking the generated output directly:
rg -n "<title>|canonical|og:title|description" dist/pricing/index.html
For a small site, that one command catches most mistakes. If the title is generic, the canonical is wrong, or the description is missing, I can fix the page metadata before deploy.
For a larger site, I turn that into a script and make the build fail. The rule is the same either way: inspect the static HTML that ships to production.
That is the whole point of prerendering. The output file is the thing search engines and preview bots see first.
]]>