DEV Community: Dakota Wu

Set Your Timeouts From Data: A 60-Request Probe Before You Ship on a Free Model Endpoint

Dakota Wu — Tue, 27 Oct 2026 13:33:55 +0000

Free model access makes the first deploy cheap. It does not make it fast, and that gap is where solo builds break. The bill stays at zero and the risk simply relocates: the first real incident is usually a completion that takes nine seconds inside a UI written for instant feedback. Two numbers prevent it, and both are measurable before the first user signs in — p95 latency and the share of calls rejected with a rate-limit status.

This walkthrough builds a 60-request probe, converts its output into named constants, and locks those constants behind a test. Everything below is stdlib Python except a single test dependency, so the measurement costs nothing but ten minutes.

What the probe measures, and what it refuses to measure

Three questions matter at this stage: how long a tiny completion takes at the 95th percentile, how often the endpoint answers with 429, and whether parallel callers make both numbers worse.

Quality, cost per token, and long-context behaviour are excluded on purpose. Those need a golden set and a separate harness; folding them into a latency probe produces one number that describes nothing.

One rule is baked into the script: it aborts after the second rate-limit response. A 429 is an instruction to stop, and a loop that retries around it turns a ten-minute measurement into a moderation problem.

Step 1 — Freeze the request

Variance in the request becomes variance in the measurement. Pin four fields: a fixed prompt, max_tokens of 4, temperature 0, and one model identifier. The reply is discarded; only the timing is kept.

Record the wall-clock hour and the network path as well. A p95 collected at 03:00 from a laptop on hotel Wi-Fi describes neither the endpoint nor the user.

Step 2 — The probe script

Save this as probe.py:

#!/usr/bin/env python3
"""Minimal latency / rate-limit probe. Stdlib only."""
import argparse
import json
import os
import threading
import time
import urllib.error
import urllib.request
from concurrent.futures import ThreadPoolExecutor

PROMPT = "Reply with the single word: ok"


def one_call(base, key, model, timeout_s):
    payload = json.dumps({
        "model": model,
        "messages": [{"role": "user", "content": PROMPT}],
        "max_tokens": 4,
        "temperature": 0,
    }).encode("utf-8")
    req = urllib.request.Request(
        base.rstrip("/") + "/chat/completions",
        data=payload,
        headers={
            "Content-Type": "application/json",
            "Authorization": "Bearer " + key,
        },
        method="POST",
    )
    started = time.perf_counter()
    try:
        with urllib.request.urlopen(req, timeout=timeout_s) as resp:
            resp.read()
            status = resp.status
    except urllib.error.HTTPError as err:
        status = err.code
    except Exception as err:  # timeouts, DNS, TLS
        status = type(err).__name__
    return {"status": status, "seconds": time.perf_counter() - started}


def quantile(values, q):
    if not values:
        return None
    ordered = sorted(values)
    idx = min(len(ordered) - 1, int(round(q * (len(ordered) - 1))))
    return round(ordered[idx], 3)


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--n", type=int, default=60)
    ap.add_argument("--concurrency", type=int, default=1)
    ap.add_argument("--sleep", type=float, default=1.0)
    ap.add_argument("--timeout", type=float, default=60.0)
    ap.add_argument("--max-429", type=int, default=2)
    ap.add_argument("--out", default="probe.json")
    args = ap.parse_args()

    base = os.environ["MC_API_BASE"]
    key = os.environ["MC_API_KEY"]
    model = os.environ["MC_MODEL"]

    stop = threading.Event()
    lock = threading.Lock()
    results = []
    limited = 0

    def worker(_):
        nonlocal limited
        if stop.is_set():
            return
        r = one_call(base, key, model, args.timeout)
        with lock:
            results.append(r)
            if r["status"] == 429:
                limited += 1
                if limited >= args.max_429:
                    stop.set()
        time.sleep(args.sleep)

    with ThreadPoolExecutor(max_workers=args.concurrency) as pool:
        list(pool.map(worker, range(args.n)))

    ok = [r["seconds"] for r in results if r["status"] == 200]
    summary = {
        "requests": len(results),
        "ok": len(ok),
        "rate_limited": limited,
        "aborted_on_429": stop.is_set(),
        "p50_s": quantile(ok, 0.50),
        "p95_s": quantile(ok, 0.95),
        "max_s": round(max(ok), 3) if ok else None,
        "concurrency": args.concurrency,
    }
    print(json.dumps(summary, indent=2))
    with open(args.out, "w", encoding="utf-8") as fh:
        json.dump({"summary": summary, "results": results}, fh, indent=2)


if __name__ == "__main__":
    main()

Two runs are enough for a first cut. The first measures a single caller; the second shows whether three parallel callers degrade each other.

export MC_API_BASE="https://<endpoint-from-docs>"
export MC_API_KEY="<your-key>"
export MC_MODEL="<model-id>"

python probe.py --n 60 --concurrency 1 --sleep 1.0 --out probe-c1.json
python probe.py --n 20 --concurrency 3 --sleep 1.0 --out probe-c3.json

A typical output block looks like this fixture — labelled as a fixture, because the real numbers belong to a real run:

{
  "requests": 60,
  "ok": 58,
  "rate_limited": 0,
  "aborted_on_429": false,
  "p50_s": 1.4,
  "p95_s": 3.1,
  "max_s": 6.8,
  "concurrency": 1
}

The gap between p95 and max is itself information. A wide spread on a single caller means queue depth in the client will not help; the endpoint is doing the waiting, so the UI has to say so.

Step 3 — Run the probe where it costs nothing

A probe aimed at a metered endpoint is a probe with a meter attached. MonkeyCode's free model access and free server option is the zero-cost place to run step 2: the script executes on the free server, close to the endpoint, which also strips local network noise out of the p95.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Two checks belong before the output is trusted. First, confirm the current request shape in the documentation — the script assumes the OpenAI-compatible /chat/completions shape, and if that assumption is wrong, only one_call() changes. Second, read the current allowance and limits on the site rather than in a screenshot; availability terms are exactly the sort of detail that moves, and the operator describes the offer only as free model access plus a free server option.

Step 4 — Turn the numbers into constants

Keep the mapping in one importable file, latency_contract.py, so the UI and the client library cannot drift apart:

"""Constants derived from a probe run. Change them with data, not with mood."""

PROFILES = {
    "inline":  {"timeout_s": 8,  "concurrency": 1, "ui": "sync response"},
    "spinner": {"timeout_s": 15, "concurrency": 2, "ui": "async with skeleton"},
    "queue":   {"timeout_s": 30, "concurrency": 1, "ui": "job row + poll"},
    "batch":   {"timeout_s": 45, "concurrency": 1, "ui": "off-hours job"},
}


def choose_profile(p95_s, rate_limited_ratio):
    if rate_limited_ratio > 0.05:
        return "batch"
    if p95_s is None:
        return "queue"          # no data yet: assume the slow case
    if p95_s < 2.0:
        return "inline"
    if p95_s < 5.0:
        return "spinner"
    if p95_s < 12.0:
        return "queue"
    return "batch"

The decision table it encodes:

p95, one caller	429 share	Profile	Client timeout	Product behaviour
under 2 s	5% or less	inline	8 s	direct response
2–5 s	5% or less	spinner	15 s	async plus skeleton
5–12 s	5% or less	queue	30 s	job row, poll every 2 s
over 12 s	any	batch	45 s	off-hours job
any	over 5%	batch	45 s	off-hours job

The rate-limit row outranks latency on purpose. A fast endpoint that refuses eight calls in a hundred is a batch endpoint wearing an inline costume.

Step 5 — Pin the choice with four tests

Four assertions are enough to stop a later refactor from quietly reintroducing optimistic timeouts:

# test_latency_contract.py
from latency_contract import PROFILES, choose_profile


def test_fast_endpoint_gets_inline():
    assert choose_profile(1.2, 0.0) == "inline"


def test_rate_limits_override_latency():
    assert choose_profile(1.2, 0.08) == "batch"


def test_unknown_latency_is_not_optimistic():
    assert choose_profile(None, 0.0) == "queue"


def test_timeouts_are_monotonic():
    order = ["inline", "spinner", "queue", "batch"]
    timeouts = [PROFILES[name]["timeout_s"] for name in order]
    assert timeouts == sorted(timeouts)

python -m pytest -q test_latency_contract.py

Step 6 — Let the limit shape one product decision

The temptation is to hide a slow endpoint behind a spinner and hope. The cheaper move is to change one screen: a feature whose p95 lands in the queue profile writes a row into SQLite, returns a job id immediately, and lets the client poll. That is roughly forty lines and no new infrastructure — and it makes the free tier's limits a design input instead of a surprise.

Accept the rest. If the probe says batch, ship the feature as an off-hours job and tell the user when it runs. Shipping today at zero cost is worth more than shipping a fake instant experience that fails at the worst moment.

Limitations and who should skip this

The probe measures one region at one hour. Sixty calls catch an order-of-magnitude problem; they do not produce a number worth publishing, and a shared free tier will move underneath the result.

Skip the whole approach when nobody is waiting on the output — an overnight pipeline does not need a p95 discussion. Skip it as well when latency is a contractual requirement with a p99 target and support escalation, because that is a purchase, not a measurement.

If the numbers matter for a launch happening today, run the two commands above and let them pick the profile. The free model access and free server option keep the experiment at zero, which is the only budget an indie build should spend on finding out.

Never Pay Twice for the Same Prompt: A Durable Generation Cache for Free-Tier Hosts

Dakota Wu — Mon, 26 Oct 2026 12:09:48 +0000

The cheapest model call is the one that never leaves the process. On a zero-budget stack, the real risk is not an invoice — it is burning a metered allowance on work that was already computed one restart ago.

This is a build-along for a single-founder setup: one app, one free host, one small model budget. The artifact is a content-addressed cache in stdlib Python plus SQLite, small enough to read in a sitting, durable enough to survive the container being recycled overnight.

Why an in-process dict dies on a free host

A dict cache is correct and useless here. Free hosts sleep, redeploy, and restart on their own schedule. Every cycle empties memory, and the next identical request is billed again.

The failure repeats in three places: a retry after a timeout, a double-submitted form, and a background job that re-runs on boot after a dirty shutdown. Each one sends the same prompt and gets the same answer for the second time.

Two conditions make this sharp on a zero-cost stack: free model access that is metered, and a free server option that can restart without notice. Both are operator-supplied availability claims from the MonkeyCode project, not guarantees of uptime or quota. Verify current terms before depending on them.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Step 1 — Hash the request, not the user

The key must describe everything that changes the output: model identifier, prompt text, and sampling parameters. Canonical JSON with sorted keys makes the hash stable across processes.

import hashlib, json

def cache_key(model: str, prompt: str, params: dict) -> str:
    payload = json.dumps(
        {"model": model, "prompt": prompt, "params": params},
        sort_keys=True, separators=(",", ":"),
    ).encode("utf-8")
    return hashlib.sha256(payload).hexdigest()

Because the model id and parameters are inside the hash, a model swap or a temperature change invalidates the entry automatically. There is no manual flush step to forget.

Step 2 — One table, one file, one writer

SQLite is enough for a solo project and it survives a process restart. WAL mode keeps reads from blocking the single writer.

import sqlite3, time

class GenCache:
    def __init__(self, path="gen_cache.sqlite3",
                 ttl_s=7 * 24 * 3600, max_bytes=32 * 1024 * 1024):
        self.ttl_s, self.max_bytes = ttl_s, max_bytes
        self.db = sqlite3.connect(path)
        self.db.execute("PRAGMA journal_mode=WAL")
        self.db.execute("""
            CREATE TABLE IF NOT EXISTS gen_cache (
                key TEXT PRIMARY KEY,
                created_at REAL NOT NULL,
                bytes INTEGER NOT NULL,
                output TEXT NOT NULL
            )""")
        self.db.commit()

    def get(self, key: str):
        row = self.db.execute(
            "SELECT created_at, output FROM gen_cache WHERE key=?", (key,)
        ).fetchone()
        if row is None:
            return None
        created_at, output = row
        if time.time() - created_at > self.ttl_s:
            self.db.execute("DELETE FROM gen_cache WHERE key=?", (key,))
            self.db.commit()
            return None
        return output

    def put(self, key: str, output: str) -> None:
        n = len(output.encode("utf-8"))
        self.db.execute(
            "INSERT OR REPLACE INTO gen_cache(key, created_at, bytes, output)"
            " VALUES (?,?,?,?)", (key, time.time(), n, output))
        self.db.commit()
        self._trim()

    def _trim(self) -> None:
        total = self.db.execute(
            "SELECT COALESCE(SUM(bytes), 0) FROM gen_cache").fetchone()[0]
        while total > self.max_bytes:
            row = self.db.execute(
                "SELECT key, bytes FROM gen_cache"
                " ORDER BY created_at ASC LIMIT 1").fetchone()
            if row is None:
                break
            self.db.execute("DELETE FROM gen_cache WHERE key=?", (row[0],))
            total -= row[1]
        self.db.commit()

The byte ceiling matters more than row count. A few long documents can consume the disk allowance on a small free instance, and eviction by age is the cheapest policy that behaves predictably.

Step 3 — Wrap the call so failures never get cached

A cache miss should be the only path to the model, and only a non-empty result should be written back. Caching an error turns a transient failure into a permanent wrong answer.

def generate(prompt, model, params, call_model, cache):
    key = cache_key(model, prompt, params)
    hit = cache.get(key)
    if hit is not None:
        return hit, "hit"
    out = call_model(model=model, prompt=prompt, **params)  # provider-specific
    if out:  # do not memoize empty or failed responses
        cache.put(key, out)
    return out, "miss"

Note the label: returning "hit" or "miss" alongside the text costs nothing and gives a counter to log. It is the difference between guessing whether the cache works and knowing.

Step 4 — A test plan that needs no API key

Run this before wiring the real client. A counting fake model proves the behavior offline in under a second.

calls = []

def fake_model(model, prompt, **params):
    calls.append(prompt)
    return "" if prompt == "fail" else f"echo:{prompt}"

cache = GenCache(path=":memory:")

out, state = generate("summarize a", "m1", {"temperature": 0}, fake_model, cache)
assert state == "miss" and len(calls) == 1

out, state = generate("summarize a", "m1", {"temperature": 0}, fake_model, cache)
assert state == "hit" and len(calls) == 1  # no second call

out, state = generate("summarize a", "m1", {"temperature": 0.7}, fake_model, cache)
assert state == "miss" and len(calls) == 2  # params bust the key

out, state = generate("fail", "m1", {}, fake_model, cache)
assert state == "miss"

out, state = generate("fail", "m1", {}, fake_model, cache)
assert state == "miss" and len(calls) == 4  # nothing cached for empty output

cache.put(cache_key("m1", "x", {}), "y")
cache.ttl_s = -1
assert cache.get(cache_key("m1", "x", {})) is None  # expiry path

The last two assertions are the ones worth keeping forever. Caching empty strings hides hard failures, and an untested expiry path is how stale text reaches production.

When to cache and when to refuse

Request shape	Cache?	Key additions	TTL
Extract fields from the same document	Yes	document hash	30 days
Summarize a support thread	Yes	thread id	7 days
Creative draft, high temperature	Yes, cautiously	temperature, seed	hours
Per-user personalized answer	Only if scoped	user id in key	minutes
Anything containing secrets or PII	Not by default	redact first	n/a
Streaming responses	Cache the final text	prompt only	per case

Two rules follow from the table. First, scope personalization into the key or leave it uncached — a shared entry leaking one user's context into another's answer is worse than any bill. Second, strip sensitive material before it touches disk, since the SQLite file is plaintext.

Limitations worth stating up front

A cache does not reduce the cost of the first call. Applications dominated by unique prompts will see a low hit rate and should not add this layer at all.

The free server option can reset the filesystem along with the process. If the SQLite file does not live on a mounted path, the cache is a best-effort optimization that may vanish between deploys — which is acceptable, because it holds derived data, never source-of-truth records.

Staleness is the other edge. A short TTL keeps answers close to the current model behavior; a long TTL keeps the hit rate high. That trade is a product decision, not a technical one, and it belongs in the config, visible in one place.

Who should skip this

Skip it for one-off scripts, for workloads with per-user-unique prompts, for regulated data that cannot be written to local plaintext storage, and for any system where a wrong cached answer would be harder to debug than a slow one. Also skip it if the app already sits behind a CDN cache that covers the same requests.

For the solo founder shipping today, the sequence is short: add the key function, add the table, count hits, then stop thinking about it. Readers who want to try the workflow without provisioning anything can start on the project's free model access and free server option, and should check the current terms before relying on either for anything load-bearing.

Ship an AI Feature Today With a Four-Rung Degradation Ladder

Dakota Wu — Tue, 20 Oct 2026 10:13:19 +0000

The cheapest way for a solo founder to ship an AI feature is to assume the model will be slow, throttled, or unaffordable before the week ends — and to encode that assumption in code rather than in a spreadsheet. The artifact below is a four-rung degradation ladder backed by a daily token ledger that refuses calls instead of warning about them. It is under a hundred lines of stdlib Python, its tests run offline with no API key, and it deploys to a free server with two environment variables.

This is not a forecasting exercise. A forecast answers "how many tokens will I use"; a ladder answers "what does the user see when the answer is zero". For an indie product, the second question is the one that decides whether the site stays up overnight while nobody is watching the dashboard.

Why a budget alert loses to a ledger

Alerts arrive after the call. A dashboard email at 3 a.m. does not stop the request that is already in flight, and by the time a human reads it the bill exists. Provider-side usage pages also lag, tokenization differs between models, and retries silently double the count.

A local ledger inverts the order: the call is refused before it is made. The number may be approximate, but the ceiling is structural. That trade — precision for an enforced boundary — is the right one when the budget is zero.

Step 1 — Fix the rung contract first

Each rung is a named behaviour with a known cost and a known quality. Write the table before writing any prompt; it is the part reviewers actually argue about.

Rung	Kind	Token cost	When it answers	User-visible quality
`cache`	free	0	identical prompt seen before	exact repeat
`primary`	model	~900	budget allows the best answer	full quality
`cheap`	model	~250	primary is refused or errors	shorter, acceptable
`static`	free	0	nothing else is affordable	templated, honest

The costs are config values, not measurements — they are the numbers the operator is willing to bet per request. Recalibrate them from one week of real usage rather than guessing twice.

Step 2 — Make the ledger refuse, not warn

# ledger.py — stdlib only, Python 3.11+
import json
from datetime import datetime, timezone
from pathlib import Path


class Ledger:
    def __init__(self, path: Path, daily_cap: int) -> None:
        self.path = path
        self.daily_cap = daily_cap

    @staticmethod
    def _today() -> str:
        return datetime.now(timezone.utc).strftime("%Y-%m-%d")

    def _state(self) -> dict:
        if not self.path.exists():
            return {"day": self._today(), "spent": 0}
        state = json.loads(self.path.read_text())
        if state.get("day") != self._today():
            return {"day": self._today(), "spent": 0}
        return state

    def reserve(self, cost: int) -> bool:
        state = self._state()
        if state["spent"] + cost > self.daily_cap:
            return False
        state["spent"] += cost
        tmp = self.path.with_suffix(".tmp")
        tmp.write_text(json.dumps(state))
        tmp.replace(self.path)
        return True

Two details matter more than they look. The day key is UTC, so the reset is not tied to whatever timezone the free server happens to boot in. The write goes through a temp file and an atomic replace, because a container that restarts mid-write should not come back with a truncated ledger and a reset budget.

Step 3 — Inject the transport so the ladder is testable

# ladder.py — the ladder itself; the provider client is a parameter
import hashlib
import json
from dataclasses import dataclass
from pathlib import Path


@dataclass(frozen=True)
class Rung:
    name: str
    cost: int
    kind: str  # "cache" | "model" | "static"


DEFAULT_RUNGS = (
    Rung("cache", 0, "cache"),
    Rung("primary", 900, "model"),
    Rung("cheap", 250, "model"),
    Rung("static", 0, "static"),
)


class JsonCache:
    def __init__(self, path: Path, limit: int = 512) -> None:
        self.path = path
        self.limit = limit
        self.data = json.loads(path.read_text()) if path.exists() else {}

    def get(self, key: str) -> str | None:
        return self.data.get(key)

    def put(self, key: str, value: str) -> None:
        self.data[key] = value
        for stale in list(self.data)[: max(0, len(self.data) - self.limit)]:
            del self.data[stale]
        self.path.write_text(json.dumps(self.data))


class Ladder:
    def __init__(self, ledger, transport, cache, rungs=DEFAULT_RUNGS,
                 fallback="The assistant is offline right now."):
        self.ledger = ledger
        self.transport = transport          # (rung_name, prompt) -> str
        self.cache = cache
        self.rungs = rungs
        self.fallback = fallback

    def respond(self, prompt: str) -> dict:
        key = hashlib.sha256(prompt.encode()).hexdigest()[:16]
        for rung in self.rungs:
            if rung.kind == "cache":
                hit = self.cache.get(key)
                if hit:
                    return {"rung": rung.name, "text": hit, "spent": 0}
                continue
            if rung.kind == "static":
                return {"rung": rung.name, "text": self.fallback, "spent": 0}
            if not self.ledger.reserve(rung.cost):
                continue
            try:
                text = self.transport(rung.name, prompt)
            except Exception:
                continue  # cost stays reserved: failed calls can still bill
            self.cache.put(key, text)
            return {"rung": rung.name, "text": text, "spent": rung.cost}
        return {"rung": "static", "text": self.fallback, "spent": 0}

Note the deliberate pessimism: a reservation is not refunded when the transport throws. Providers can bill partial output on a dropped stream, and a ledger that assumes refunds is a ledger that under-counts exactly when things are going wrong.

Step 4 — Test the sad paths before the happy one

The happy path is the least interesting thing this code does. The tests that matter prove the ceiling holds when the budget is gone and when the provider is down.

# test_ladder.py
import tempfile, unittest
from pathlib import Path
from ladder import Ladder, Ledger, Rung, JsonCache
from ledger import Ledger as _Ledger  # same class, imported for clarity

RUNGS = (Rung("cache", 0, "cache"), Rung("primary", 900, "model"),
         Rung("cheap", 250, "model"), Rung("static", 0, "static"))


class LadderCase(unittest.TestCase):
    def setUp(self):
        self.dir = Path(tempfile.mkdtemp())
        self.cache = JsonCache(self.dir / "cache.json")

    def make(self, cap, transport):
        return Ladder(Ledger(self.dir / "ledger.json", cap), transport,
                      self.cache, RUNGS, "offline")

    def test_cap_forces_static(self):
        ladder = self.make(1000, lambda rung, prompt: "ok")
        self.assertEqual(ladder.respond("first")["rung"], "primary")
        self.assertEqual(ladder.respond("second")["rung"], "static")

    def test_cache_hit_is_free(self):
        ladder = self.make(1000, lambda rung, prompt: "ok")
        ladder.respond("same")
        second = ladder.respond("same")
        self.assertEqual(second["rung"], "cache")
        self.assertEqual(second["spent"], 0)

    def test_primary_failure_falls_to_cheap(self):
        def flaky(rung, prompt):
            if rung == "primary":
                raise RuntimeError("503")
            return "cheap answer"
        result = self.make(5000, flaky).respond("hello")
        self.assertEqual(result["rung"], "cheap")


if __name__ == "__main__":
    unittest.main()

Run it with python -m unittest -q test_ladder.py. Three tests, no network, no key. In the second test the cap is 1000 while primary costs 900, which is why the second distinct prompt can only reach static — the assertion is about the ceiling, not about the model.

Step 5 — Rehearse on a list, then deploy

Before pointing real traffic at this, replay a short list of the prompts your product actually receives and print which rung would answer each one under a shrunken cap.

# rehearse.py — dry run, no provider call
from pathlib import Path
from ladder import Ladder, Rung, JsonCache
from ledger import Ledger

PROMPTS = ["summarise this changelog", "summarise this changelog",
           "explain this stack trace", "draft a release note"]

ladder = Ladder(Ledger(Path("rehearsal.json"), 1200),
                lambda rung, prompt: f"SIMULATED via {rung}",
                JsonCache(Path("rehearsal-cache.json")))
for prompt in PROMPTS:
    result = ladder.respond(prompt)
    print(f"{result['rung']:>8} | {result['spent']:>4} | {prompt}")

A rehearsal that shows every prompt landing on primary means the cap is decorative. The useful outcome looks like primary for the first prompt, cache for the repeat, and static or cheap once the rehearsal budget drains — that is the shape a user will actually experience on a bad day.

Deployment is two variables and one process: DAILY_TOKEN_CAP and LEDGER_PATH on a mounted volume, with the ledger file outside the container image. On a small free host the cache and ledger are plain files, so nothing needs a database. A single curl against your own page after deploy, with the cap set to 0, is the fastest proof that the static rung renders instead of a 500.

Free model access and a free server option are what make this workflow realistic for one person, because the cliff arrives at zero spend rather than at the first invoice. MonkeyCode is the tool this build used for the model calls and the deployment; at the time of writing the operator advertises a 10 million token free allowance plus a free server option, and both belong in your own notes as a figure to re-check on the pricing page before you rely on them — allowances change, and a hard-coded quota is worse than no quota. The ladder does not depend on that number: set DAILY_TOKEN_CAP to whatever the current terms support.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

What this ladder cannot do

Estimate honestly. 900 and 250 are bets. Real tokenization varies by prompt length, language, and output style.
Stop provider-side spend. If the same key is used by another script, the ledger knows nothing about it. One key per ledger is the only safe mapping.
Expire cache entries. There is no TTL in JsonCache; a stale answer can outlive the fact it described. Add timestamps if the content is time-sensitive.
Guarantee consistency under concurrency. Two processes can both pass reserve before either writes. A file lock or a single-writer queue fixes it; a solo deploy with one worker usually does not need it.

Who should not use this

Teams that need per-customer quotas, invoices that reconcile to the token, or auditable cost attribution should use provider-side budgets and a real billing pipeline instead. Products where a degraded answer is worse than no answer — anything medical, legal, or security-decisioning — should skip the cheap and static rungs entirely and return an explicit failure. And anyone whose workload is unbounded by nature, such as open-ended agent loops, needs a hard iteration cap before a token cap means anything.

For the solo case the trade is simple: accept approximate counting, accept a templated fallback, and ship today with a ceiling you can explain to yourself in one sentence. If you want to try the ladder on a zero bill, the free model access on MonkeyCode is the path this build took — the code above is the same either way.

A Pre-Prompt Redaction Gate for Solo Repos

Dakota Wu — Mon, 19 Oct 2026 08:55:56 +0000

Most AI coding leaks on a solo repo are boring. A founder pastes a stack trace, a .env line, an internal hostname, and a customer email into a chat box, takes the patch, and ships. Nobody reviews the prompt because nobody else is in the room.

A gate beats discipline here. The artifact below is a stdlib-only redactor that runs before the prompt is written, proves itself against a fixture of planted secrets, and rehydrates the model's answer on your own machine. It adds no dependencies, no service, and no bill. It runs on whatever box already builds the project.

The three classes of payload

Inventory first. Regex written before inventory always misses the obvious case.

Prefixed credentials. Cloud access keys, sk_-style API keys, bearer headers, credentials embedded in connection URLs.
Identity and topology. Emails, private IPs, .internal / .corp hostnames, absolute home paths.
Unpatterned business context. Table names, customer names, invoice fields, unreleased flags.

Classes 1 and 2 are mechanical. Class 3 is not, and a redactor that claims to handle it will be trusted once and abandoned after the first bad paste. Treat this tool as a floor, not a ceiling.

Step 1 — Write the redactor

One file, standard library only. Rules run in a fixed order because URL credentials must be captured before the email rule shreds them.

#!/usr/bin/env python3
# redact.py - stdlib-only pre-prompt redaction with local rehydration.
import argparse, json, re
from pathlib import Path

RULES = [
    ('URL_CRED', re.compile(r'(?i)\b[a-z][a-z0-9+.-]*://[^/\s:@]+:[^/\s@]+@')),
    ('CLOUD_KEY', re.compile(r'\b(?:AKIA|ASIA)[0-9A-Z]{16}\b')),
    ('API_KEY', re.compile(r'\b(?:sk|rk|pk)[_-](?:live|test)?[_-]?[A-Za-z0-9]{16,}\b')),
    ('BEARER', re.compile(r'(?i)\bbearer\s+[A-Za-z0-9._~+/=-]{20,}')),
    ('INTERNAL_HOST', re.compile(r'\b[a-z0-9][a-z0-9-]*\.(?:internal|corp|local|lan|svc)\b', re.I)),
    ('PRIVATE_IP', re.compile(r'\b(?:10\.\d{1,3}|192\.168|172\.(?:1[6-9]|2\d|3[01]))\.\d{1,3}\.\d{1,3}\b')),
    ('ABS_PATH', re.compile(r'/(?:Users|home)/[A-Za-z0-9._-]+')),
    ('EMAIL', re.compile(r'\b[\w.+-]+@[\w-]+\.[\w.]{2,}\b')),
]

def redact(text):
    mapping = {}
    out = text
    for label, pattern in RULES:
        def swap(match, label=label):
            token = f'<{label}_{len(mapping) + 1}>'
            mapping[token] = match.group(0)
            return token
        out = pattern.sub(swap, out)
    return out, mapping

def rehydrate(text, mapping):
    for token in sorted(mapping, key=len, reverse=True):
        text = text.replace(token, mapping[token])
    return text

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument('--in', dest='src', required=True)
    ap.add_argument('--out', dest='dst', required=True)
    ap.add_argument('--map', dest='map', required=True)
    args = ap.parse_args()
    raw = Path(args.src).read_text(encoding='utf-8')
    red, mapping = redact(raw)
    Path(args.dst).parent.mkdir(parents=True, exist_ok=True)
    Path(args.dst).write_text(red, encoding='utf-8')
    Path(args.map).write_text(json.dumps(mapping, indent=2), encoding='utf-8')
    print(f'redacted {len(mapping)} spans -> {args.dst}')

if __name__ == '__main__':
    main()

The mapping file is the whole trick. Placeholders keep the prompt readable for the model, and the map lets you swap real values back into the answer afterwards. It also creates a new secret store, which the limitations below take seriously.

Step 2 — Prove it with a leak test

A gate you cannot test is a ritual. Plant known values, redact, then assert that none survive and that clean SQL passes untouched.

# test_redact.py
import unittest
from redact import redact, rehydrate

LEAKY = '''\
debug: postgres://app:hunter2@db.corp.internal:5432/app
key: sk_live_51H8xQ2eZvKYlo2C
contact: ops@acme-billing.example
host: 10.4.19.7
path: /Users/dakota/work/client-x/pipeline.py
'''

CLEAN = 'SELECT id, total FROM orders WHERE total > 100;\n'

class RedactionTest(unittest.TestCase):
    def test_every_planted_value_is_gone(self):
        red, mapping = redact(LEAKY)
        self.assertGreaterEqual(len(mapping), 5)
        for secret in mapping.values():
            self.assertNotIn(secret, red)

    def test_round_trip_rehydrates(self):
        red, mapping = redact(LEAKY)
        self.assertEqual(rehydrate(red, mapping), LEAKY)

    def test_plain_sql_is_untouched(self):
        red, mapping = redact(CLEAN)
        self.assertEqual(red, CLEAN)
        self.assertEqual(mapping, {})

if __name__ == '__main__':
    unittest.main()

Run it:

python3 -m unittest -q test_redact

----------------------------------------------------------------------
Ran 3 tests in 0.001s

OK

The round-trip test is the one that catches regressions. Widen a rule too far and it fails, because the sloppy rule swallowed text that had to survive.

Step 3 — Make the gate unavoidable

Hooks beat habits. This pre-commit redacts changed raw prompts, stages the redacted copies, refuses to commit the rehydration map, and re-runs the suite.

#!/usr/bin/env bash
set -euo pipefail

git check-ignore -q .redact-map.json || {
  echo 'gate: add .redact-map.json to .gitignore first' >&2; exit 1; }

if git diff --cached --name-only | grep -qx '.redact-map.json'; then
  echo 'gate: refusing to commit the rehydration map' >&2; exit 1
fi

for f in prompts/raw/*.md; do
  [ -e "$f" ] || continue
  base="${f##*/}"
  python3 redact.py --in "$f" --out "prompts/redacted/$base" --map .redact-map.json
  git add "prompts/redacted/$base"
done

python3 -m unittest -q test_redact

Install and verify the ignore rule:

printf '.redact-map.json\n' >> .gitignore
cp hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
git check-ignore -v .redact-map.json

.gitignore:1:.redact-map.json   .redact-map.json

Ordering matters. The ignore check runs first, so a missing .gitignore line fails before any prompt is written to disk.

Step 4 — Send the redacted file, rehydrate locally

Only prompts/redacted/*.md should ever leave the machine. Paste that file, take the answer back, and map it:

python3 - <<'PY'
import json
from pathlib import Path
from redact import rehydrate
mapping = json.loads(Path('.redact-map.json').read_text())
answer = Path('out/model-answer.md').read_text()
Path('out/answer.local.md').write_text(rehydrate(answer, mapping))
PY

The redacted prompt is portable across providers. That is deliberate, and it is why the same file works with MonkeyCode's free model access and free server option: small text-only payloads, sensitive spans already abstracted out. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The operator states a 10M-token free allowance and a free server option as of this writing; rosters, limits, and terms change, and nothing here independently verifies current numbers, so check them before planning around them.

One caveat on the free server lane: the map lives on that box. Rebuild the box and the map is gone, so previously redacted answers can no longer be rehydrated. Keep the map on the laptop that owns the secrets, not on the machine that runs the build.

Decision table

Payload	Redactor only	Redactor + human read	Never send
Open-source file you did not write	ok	—	—
Your own app code, no customer data	ok	—	—
Stack trace from production	ok	yes	—
Schema plus sample rows	—	yes	—
`.env`, keystore, kubeconfig	—	—	never
Customer PII or payment data	—	—	never

Two rows are absolute. Config dumps and personal data stay local regardless of how good the rule set looks, because both fail on class 3, not class 1.

Limitations and who should skip this

Entropy-free secrets pass through. A bare password such as hunter2, with no prefix and no surrounding URL, matches nothing here. Prefix rules are cheap; general secret detection is not.
Base64 and screenshots defeat it. A pasted image of a terminal, or an encoded blob of config, bypasses every regex above.
Semantic leaks remain. Table names and customer names are class 3, and no pattern in this file can see them.
The map is now sensitive. It holds, in plain JSON on disk, the exact values the gate was hiding.
Redaction is not compliance. Passing this gate does not make a hosted free model acceptable for regulated data.

Skip the approach if the repo touches health, payment, or identity data — no free hosted model belongs in that path, gate or not. Skip it as well if CI already runs a real secret scanner; this is a last-mile prompt gate, not an inventory tool, and it will feel redundant next to gitleaks. Skip it too if a license or client contract forbids sending source to third parties at all, because redaction does not change what the file is.

If one thing from this post gets kept, keep the leak test. The rule list is replaceable. The fixture that fails loudly when a rule rots is the part that keeps the gate honest a month from now.

Audit Context Re-Send Before You Trust a Free Token Allowance

Dakota Wu — Sun, 18 Oct 2026 07:31:17 +0000

Core conclusion: in a multi-turn agent loop, the transcript you resend — not the model's reply — decides whether a free token allowance survives the day. Measure the re-send multiplier on one real run before building a workflow on top of it.

Small teams tend to budget by output length. That is the wrong variable. Every turn ships the whole prior conversation back as input, so consumption grows quadratically while the visible artifact (the answer) grows linearly.

The multiplier, in one worked example

Assume a loop that produces roughly 400 tokens per reply and resends full history each turn. These numbers are illustrative arithmetic, not a benchmark.

Turn 1 input: 0 prior tokens.
Turn 5 input: ~1,600 prior tokens.
Turn 20 input: ~7,600 prior tokens.
Cumulative input across 20 turns: ~76,000 tokens. Cumulative output: ~8,000.

A 9.5:1 input-to-output ratio. Retries make it worse, because a failed turn usually gets retried with the failure text appended — history grows and the loop immediately pays for the growth again.

An operator-stated free allowance is a real constraint under that arithmetic. At the time of writing, the operator of the open-source MonkeyCode project states a free token allowance and a free server option; both are promotional availability claims that can change, so read the current project page before planning around specific numbers. The method below works regardless of where the tokens come from.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Step 1 — Record one honest loop

The audit needs a transcript, not a mental model of the loop. Log every turn as JSONL with the prompt actually sent and the reply actually received. If the provider returns usage numbers, store them too — they calibrate the estimate later.

{"turn": 1, "prompt": "summarize issue 41", "reply": "...", "usage_input": 812}
{"turn": 2, "prompt": "now write the patch", "reply": "...", "usage_input": 1930}

One constraint: record a run that failed at least once. Clean runs understate the multiplier by a wide margin, and the failure path is usually where indie budgets die.

Step 2 — Estimate re-send with bytes, then calibrate

A tokenizer is optional for this. Counting UTF-8 bytes and dividing by four gives a usable proxy in the same order of magnitude, and the script below prints the calibration ratio when real usage numbers exist.

#!/usr/bin/env python3
"""audit_loop.py - estimate context re-send from a JSONL transcript.

Proxy: 1 token ~= 4 UTF-8 bytes. Estimate only, not a tokenizer.
Usage: python3 audit_loop.py transcript.jsonl [--ceiling 200000]
"""
import argparse
import json
import sys
from pathlib import Path

BYTES_PER_TOKEN = 4


def estimate(text: str) -> int:
    return max(1, len(text.encode("utf-8")) // BYTES_PER_TOKEN)


def load(path: Path) -> list[dict]:
    rows = []
    with path.open(encoding="utf-8") as fh:
        for line in fh:
            line = line.strip()
            if line:
                rows.append(json.loads(line))
    return rows


def main() -> int:
    ap = argparse.ArgumentParser()
    ap.add_argument("transcript", type=Path)
    ap.add_argument("--ceiling", type=int, default=0)
    args = ap.parse_args()

    rows = load(args.transcript)
    history = 0
    cumulative_in = 0
    cumulative_out = 0
    measured_in = 0

    print(f"{'turn':>4} {'in_proxy':>9} {'out_proxy':>9} {'cum_in':>9}")
    for i, row in enumerate(rows, start=1):
        out_tok = estimate(row.get("reply", ""))
        in_tok = history + estimate(row.get("prompt", ""))
        history += out_tok
        cumulative_in += in_tok
        cumulative_out += out_tok
        measured_in += int(row.get("usage_input") or 0)
        print(f"{i:>4} {in_tok:>9} {out_tok:>9} {cumulative_in:>9}")

    if cumulative_out and cumulative_in:
        ratio = cumulative_in / cumulative_out
        print(f"\ninput/output ratio: {ratio:.1f}:1")
    if measured_in:
        ratio = measured_in / cumulative_in
        print(f"calibration vs reported usage: {ratio:.2f}x")
        print("  (>1.5x or <0.67x means retune BYTES_PER_TOKEN)")

    print(f"cumulative input proxy: {cumulative_in} tokens")
    if args.ceiling and cumulative_in > args.ceiling:
        print("verdict: run exceeded ceiling", file=sys.stderr)
        return 2
    return 0


if __name__ == "__main__":
    sys.exit(main())

python3 audit_loop.py transcript.jsonl --ceiling 200000
echo "exit=$?"

Exit code 2 is deliberate. It lets the audit slot into a pre-commit hook or a CI step without anyone parsing prose.

Step 3 — Gate the loop with a daily ledger

An audit is a measurement; a gate is a policy. The gate is a small append-only file with one row per call, fsynced so a crash cannot erase the evidence.

#!/usr/bin/env python3
"""gate.py - daily token ceiling for a single-process agent loop."""
import json
import os
import sys
import time
from pathlib import Path

LEDGER = Path(os.environ.get("LOOP_LEDGER", "budget.jsonl"))
CEILING = int(os.environ.get("LOOP_DAILY_TOKENS", "0"))


def spent_today() -> int:
    day = time.strftime("%Y-%m-%d")
    if not LEDGER.exists():
        return 0
    total = 0
    for line in LEDGER.read_text(encoding="utf-8").splitlines():
        if not line.strip():
            continue
        row = json.loads(line)
        if row.get("day") == day:
            total += int(row.get("tokens", 0))
    return total


def charge(tokens: int, tag: str) -> None:
    row = {
        "day": time.strftime("%Y-%m-%d"),
        "ts": int(time.time()),
        "tokens": tokens,
        "tag": tag,
    }
    with LEDGER.open("a", encoding="utf-8") as fh:
        fh.write(json.dumps(row) + "\n")
        fh.flush()
        os.fsync(fh.fileno())


def preflight(estimated: int, tag: str = "run") -> bool:
    if CEILING <= 0:
        return True
    used = spent_today()
    if used + estimated > CEILING:
        print(f"refuse tag={tag} used={used} est={estimated} ceiling={CEILING}",
              file=sys.stderr)
        return False
    return True

export LOOP_DAILY_TOKENS=250000
python3 -c "import gate; print(gate.preflight(40000, 'nightly'))"

Two rules keep this honest. Charge before the call with the estimate, then charge again after with the real number and a settle tag; and set the ceiling below the allowance, not at it, because the proxy drifts on code-heavy prompts.

Step 4 — Shrink the transcript instead of the model

The cheapest fix is not a smaller model. It is a smaller history. Replace full-history resend with a rolling summary capped at a fixed byte budget.

import os
from pathlib import Path


def roll(summary_path: str, new_reply: str, cap: int = 2000) -> None:
    p = Path(summary_path)
    prev = p.read_text(encoding="utf-8") if p.exists() else ""
    merged = (prev + "\n" + new_reply.strip()).strip()
    raw = merged.encode("utf-8")
    if len(raw) > cap:
        merged = raw[-cap:].decode("utf-8", errors="ignore")
        merged = merged.split("\n", 1)[-1]
    tmp = p.with_suffix(".tmp")
    tmp.write_text(merged, encoding="utf-8")
    os.replace(tmp, p)

Run the audit again after the swap. A loop that drops from 9:1 to 3:1 input-to-output typically fits a free allowance for a full day of iteration, which is the whole point for a solo build.

Where each option fits

Situation	Full history resend	Rolling summary	Fresh single call
First prototype, one file	fine	overkill	fine
Multi-step refactor, 20+ turns	costs spiral	recommended	loses context
Nightly scripted job	avoid	recommended	recommended
Debugging a single failure	fine	hides the trace	fine

The free server option is the natural host for the gate and the ledger, since both are tiny and stateful. Whether it fits a given workload depends on current limits, so check the project page rather than a blog post — including this one.

Limits and who should skip this

The byte proxy misjudges CJK text, minified code, and base64 blobs. Calibrate against reported usage before trusting the ceiling.
The ledger assumes one writer. Two concurrent processes will double-count or race; use a lock or one ledger per process.
Free allowances and free server availability are promotional and can change without notice. Nothing here guarantees capacity.
Skip this if you need an SLA, deterministic latency, or auditable per-request billing. A paid provider with metered invoices is the correct tool there.

For an indie route shipped today, the sequence is short: record one loop, audit the multiplier, gate the day, shrink the transcript. If the open-source MonkeyCode project is the host you want to try, the free model access and free server option are the two things to verify on its current page before you commit a build to them.

Detect Silent Model Drift With a Stdlib-Only Golden Set Harness

Dakota Wu — Fri, 16 Oct 2026 05:35:37 +0000

Detect Silent Model Drift With a Stdlib-Only Golden Set Harness

A hosted model can change between two of your deploys, and nothing in your lockfile moves. Your unit tests still pass, your container still builds, and your users still get slightly different JSON than they got last Tuesday. The practical fix is not a bigger test suite; it is a frozen golden set, a deterministic scorer, and an append-only ledger that fails the run when the pass rate drops below a floor.

This article builds exactly that, using only the Python standard library. It runs on a free-tier host, it costs one file of input data, and it answers a single narrow question: did the contract my product depends on stop holding?

Why ordinary tests miss model drift

Application tests assert on code you control. A model response is an input from outside your repository, and it arrives as free text that happens to be parseable.

When a provider adjusts decoding defaults, swaps capacity, or routes you to a different checkpoint, the shape of the output can shift while the API status code stays 200. Nothing throws. The failure surfaces later, as a support message about a field that used to be filled in.

A golden set inverts that. Instead of asserting on the current behavior, it asserts on a small number of hand-checked examples that were correct on a specific day, and it keeps the receipts.

Step 1: Freeze a small golden set as JSONL

The input file is plain JSONL, one contract per line. Keep it small on purpose: 20 to 40 cases is enough to catch a formatting or label flip, and it fits inside a free-tier request budget.

{"id":"invoice_date","input":"Invoice paid 2026-03-04, net 30 days.","expect":{"label":"invoice","fields":{"due_date":"2026-04-03"}}}
{"id":"refund_request","input":"I want my money back for order 8812, it never arrived.","expect":{"label":"refund","fields":{"order_id":"8812"}}}
{"id":"no_action","input":"Thanks, the docs answered my question.","expect":{"label":"none","fields":{}}}

Every line has three parts: an id you will grep for in the ledger, the raw input you send, and the expect object you compare against. Do not paste generated examples into this file. If you did not read the output and agree with it, it does not belong in the baseline.

Step 2: Write a transport adapter that assumes nothing

The runner below assumes an OpenAI-style /chat/completions request body. That assumption is isolated in one function so you can replace it when your endpoint differs.

#!/usr/bin/env python3
"""golden_run.py - regression run against a chat endpoint. Stdlib only."""
import json, os, sys, time, hashlib, pathlib, urllib.request

BASE = os.environ["MODEL_BASE_URL"].rstrip("/")
KEY = os.environ["MODEL_API_KEY"]
MODEL = os.environ["MODEL_ID"]
GOLDEN = pathlib.Path(os.environ.get("GOLDEN", "golden.jsonl"))
LEDGER = pathlib.Path(os.environ.get("LEDGER", "ledger.jsonl"))

SYSTEM = (
    "You are a strict extractor. Return ONLY minified JSON shaped as "
    '{"label": string, "fields": object}. Omit absent fields. '
    "No prose, no markdown fences."
)

def call(text, timeout=30):
    body = json.dumps({
        "model": MODEL,
        "temperature": 0,
        "messages": [{"role": "system", "content": SYSTEM},
                     {"role": "user", "content": text}],
    }).encode()
    req = urllib.request.Request(
        f"{BASE}/chat/completions", data=body,
        headers={"Content-Type": "application/json",
                 "Authorization": f"Bearer {KEY}"},
    )
    with urllib.request.urlopen(req, timeout=timeout) as r:
        payload = json.loads(r.read())
    return payload["choices"][0]["message"]["content"]

Keep temperature at zero when the endpoint supports it. If the parameter is rejected or ignored, note that in your README rather than deleting it, because a later comparison depends on knowing what you actually sent.

Step 3: Score the contract, not the prose

Scoring is exact after light normalization: trim, lowercase, collapse whitespace. That is deliberately unforgiving, because the goal is to detect change, not to grade writing.

def norm(v):
    return " ".join(v.strip().lower().split()) if isinstance(v, str) else v

def score(case, raw):
    try:
        got = json.loads(raw)
    except json.JSONDecodeError:
        return {"case": case["id"], "ok": False, "why": "invalid_json"}
    want = case["expect"]
    if norm(got.get("label")) != norm(want["label"]):
        return {"case": case["id"], "ok": False, "why": "label",
                "got": got.get("label"), "want": want["label"]}
    fields, gotf = want.get("fields", {}), (got.get("fields") or {})
    for k, v in fields.items():
        if norm(gotf.get(k)) != norm(v):
            return {"case": case["id"], "ok": False, "why": f"field:{k}",
                    "got": gotf.get(k), "want": v}
    return {"case": case["id"], "ok": True, "why": "pass"}

Two failure reasons are distinguishable here and that distinction is the whole point: invalid_json is a format drift, label or field:* is a content drift.

Step 4: Append every run to a ledger and exit non-zero

The ledger is one JSON object per line, append-only, with a run_id derived from the system prompt, model id, and base URL. Change any of those and the id changes, which keeps old and new comparisons honest.

def run():
    run_id = hashlib.sha256(
        (SYSTEM + MODEL + BASE).encode()).hexdigest()[:12]
    rows = []
    for line in GOLDEN.read_text().splitlines():
        line = line.strip()
        if not line or line.startswith("#"):
            continue
        case = json.loads(line)
        raw, err = "", None
        for attempt in range(3):
            try:
                raw = call(case["input"])
                break
            except Exception as exc:      # timeout, 429, DNS, 5xx
                err, raw = repr(exc), ""
                time.sleep(2 ** attempt)
        if not raw:
            rows.append({"case": case["id"], "ok": False,
                         "why": "transport", "err": err})
            continue
        r = score(case, raw)
        r["raw"] = raw[:400]
        rows.append(r)
    total, passed = len(rows), sum(r["ok"] for r in rows)
    rate = round(passed / total, 3) if total else 0.0
    record = {"run_id": run_id, "ts": int(time.time()), "total": total,
              "passed": passed, "rate": rate, "rows": rows}
    with LEDGER.open("a") as fh:
        fh.write(json.dumps(record) + "\n")
    print(f"{passed}/{total} ({rate:.0%}) run_id={run_id}")
    floor = float(os.environ.get("PASS_FLOOR", "0.9"))
    return 0 if total and rate >= floor else 1

if __name__ == "__main__":
    sys.exit(run())

Exit codes matter more than dashboards when you are alone. Non-zero from this script can page you, block a deploy, or simply stop a scheduled job from marking the day green.

Step 5: Run it on a schedule without paying for a scheduler

On a free-tier host, cron is the cheapest scheduler you have. Secrets stay in a .env file that the job sources, so the crontab itself contains no keys.

# /srv/app/run-golden.sh
set -euo pipefail
cd /srv/app
set -a; . ./.env; set +a
python3 golden_run.py >> /var/log/golden.log 2>&1

# off-peak, once a day; adjust to the hour your host is quietest
17 4 * * * /srv/app/run-golden.sh

Compare the last two runs with one command. The jq filter prints only the cases that flipped.

tail -n 2 ledger.jsonl \
  | jq -c '{run_id, ts, rate, fails: [.rows[] | select(.ok == false) | .case]}'

Free-tier containers often sleep between requests. A 30-second timeout and a three-attempt backoff absorb most cold-start noise, and the transport reason keeps that noise out of your content-drift count.

Reading the ledger: a decision table

Signal in the ledger	Likely cause	First action
Many `transport`, few content failures	throttling, cold start, or a slow window	Move the job off-peak, lower case count, raise timeout
Sudden `invalid_json` on every case	response formatting default changed	Re-check the adapter and system prompt before blaming the model
One field fails on most cases	real content change	Pin a previous model id if one is offered, or add a normalization step
One case fails, everything else passes	a genuinely hard example	Re-read the expected value; the baseline may be wrong

A single bad run is not a verdict. Two consecutive runs with the same failure set is the threshold worth acting on.

Limitations and who should skip this

Exact-match scoring is brittle by design and wrong for open-ended generation. Do not point this harness at a summarizer, a chat assistant, or anything whose value is in the phrasing.

A 20-to-40 case set cannot detect rare failures, and it gives no statistical confidence. Teams that need eval coverage, graders, or per-release reports should use a real evaluation platform instead.

The adapter is single-turn. Agents that call tools across multiple round trips need a different harness, or at least a recorded-transcript replay layer in front of this one.

Finally, the runtime budget is real. Free-tier quotas, sleep windows, and timeouts change; the ledger tells you when they did, but it will not make them go away.

Where MonkeyCode fits in this loop

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

The harness is endpoint-agnostic, which is the point. In my own loop, MonkeyCode is the endpoint behind MODEL_BASE_URL and the host that runs the cron job, because its free model access and free server option keep a nightly regression run off the invoice while the project is still pre-revenue. The operator describes the free tier as including a substantial token allowance — on the order of ten million tokens — plus a free server option; verify the current terms on the project page before you size a golden set against it, since quotas and limits move faster than articles do. The project is open source, so the transport adapter is the only part you may need to touch.

If the loop is useful, the smallest honest start is one line in golden.jsonl: take a real failure your users already reported, freeze the correct output, and let the ledger watch it for you.

Cap Repair Attempts Before a Free Server Restarts

Dakota Wu — Tue, 13 Oct 2026 03:01:18 +0000

A solo route keeps a zero bill only when each model repair has a local attempt ceiling and a frozen process set. An agreeable patch that adds a listener, a worker, or a second runtime is a failed deploy, not a green check. The workflow below is a local gate for that failure. It does not read a vendor dashboard, and it does not require a paid host.

Free model access makes the loop easier to start. Each retry looks cheap until the free server is restarting a process the original route never declared. The gate records attempts on disk, refuses a wider surface, and stops the loop before the host becomes a second product.

What the gate protects

The protected unit is one process, one port, and one deploy command. Health checks, billing agents, and background trainers stay outside that unit. Patterns that pin a waitlist byte ceiling, or that keep probes off a model, solve different failures. This gate only answers whether another repair attempt is still allowed on the same change.

Two files hold the contract. surface.json freezes the command, the port, and the paths the route may touch. attempts.json counts repair rounds for one change id. Both files live in the repo. Neither file calls a model.

Numbered workflow

Freeze the surface before any model call. Write the binary name, the listen port, and the paths the route may touch. Commit that file with the route, not after the first failure.
Assign a change id. A short slug plus the calendar date is enough. Reuse of an id continues the same attempt count, including across a laptop sleep or a free-host restart.
Request one patch for that change id. Store the raw suggestion next to the attempt record. Do not apply it, and do not restart the host, until the gate exits zero.
Run the local gate. The gate rejects a suggestion that names a forbidden worker, binds a port other than the frozen port, edits a path outside the freeze, or claims success without an assertion.
Apply only a suggestion that passes. Restart the single process named in the surface file. Record the process exit status beside the change id.
Stop when the attempt count hits the ceiling, even if the next suggestion sounds more confident than the last. Ship the last known-good tree, or revert the change id entirely.

The ceiling in the example is three attempts. That number is a local policy chosen for a solo afternoon. It is not a vendor quota, and it is not a measured optimum. Operators who need a longer investigation should edit the constant in the repo, not bury a higher number in a prompt.

Surface file

The freeze is small enough to review by eye. Forbidden markers name libraries that imply a second runtime. The port field is the only listen target the suggestion may mention.

{
  "change_id": "route-quote-2026-10-13",
  "command": ["python3", "app.py"],
  "port": 8080,
  "allowed_paths": ["app.py", "tests/test_quote.py"],
  "forbidden_markers": ["celery", "gunicorn", "rq.Worker", "multiprocess"]
}

A comment that explains why gunicorn is absent can false-positive if the word appears in the diff. That is acceptable for a first gate. A false reject costs one edit. A false accept costs an extra process on a host that was chosen because the bill had to stay at zero.

Unexecuted gate

The script is a proposal. It has not been executed against a live host for this draft. It reads the two JSON files, scores the suggestion, and exits non-zero when the repair must stop. It opens no socket.

#!/usr/bin/env python3
"""Local repair gate. Unexecuted example. No network calls."""
import json
import re
import sys
from pathlib import Path

CEILING = 3
ROOT = Path(".")
surface = json.loads((ROOT / "surface.json").read_text())
attempts = json.loads((ROOT / "attempts.json").read_text())
suggestion = Path(sys.argv[1]).read_text()

def fail(reason):
    print(json.dumps({"ok": False, "reason": reason}))
    raise SystemExit(2)

change_id = surface["change_id"]
count = int(attempts.get(change_id, 0))
if count >= CEILING:
    fail("attempt ceiling reached")

for marker in surface["forbidden_markers"]:
    if marker in suggestion:
        fail("surface widened by marker: " + marker)

found_ports = {int(p) for p in re.findall(r":(\d{2,5})", suggestion)}
extra_ports = found_ports - {int(surface["port"])}
if extra_ports:
    fail("extra ports: " + ",".join(str(p) for p in sorted(extra_ports)))

allowed = set(surface["allowed_paths"])
for line in suggestion.splitlines():
    if not line.startswith("+") or line.startswith("+++"):
        continue
    for token in re.findall(r"[\w./-]+\.py", line[1:]):
        if token not in allowed:
            fail("path outside freeze: " + token)

lower = suggestion.lower()
claims_done = ("all tests pass" in lower) or ("lgtm" in lower)
if claims_done and ("assert " not in suggestion):
    fail("agreeable patch without an assertion")

attempts[change_id] = count + 1
(ROOT / "attempts.json").write_text(json.dumps(attempts, indent=2) + "\n")
print(json.dumps({"ok": True, "attempts": attempts[change_id]}))

Seed the counter as an empty object before the first run. Then point the gate at the saved suggestion.

echo '{}' > attempts.json
python3 repair_gate.py suggestion.diff
echo "gate_exit=$?"

A non-zero status means the host stays on the previous tree. The suggestion remains in the working directory as evidence. It is not the deployed tree.

Known-good snapshot

Before the first model call, record the commit the host is already running. The gate does not create this snapshot. A human does, so a ceiling hit has a place to return.

git rev-parse HEAD > known_good.txt
git status --short

If known_good.txt is empty, the workflow stops. There is no honest revert target, and a free server should not be the place where the only copy of the route lives. Push the known-good commit to the remote the operator already uses, then start the repair loop.

Restart wrapper

The restart is a separate command, and it stays dumb. It refuses to launch when the gate files are missing, and it launches only the command list from the surface file. No shell string is interpolated from the model suggestion.

#!/bin/sh
set -eu
test -f surface.json
test -f attempts.json
python3 - <<'PY'
import json, os
s = json.load(open("surface.json"))
os.execvp(s["command"][0], s["command"])
PY

execvp replaces the shell with the frozen command. A model suggestion cannot append a second binary to that launch path unless a human edits surface.json on purpose. That edit is a new change id, with its own counter at zero, and it should be rare on a free server.

After the process is up, confirm a single listener. If ss is absent on the host, skip the check rather than binding the port from a probe. A probe that binds the live port is a self-inflicted outage.

ss -ltnp | awk 'NR==1 || /:8080/'
pgrep -af 'python3 app.py'

Two matching lines in the process list mean the surface broke. Roll back before asking the model for a story about why both processes are fine.

Decision table

Signal	Attempt count	Action
Forbidden marker or extra port	any, below ceiling	Reject the patch. Do not send a retry prompt that says to try again more carefully.
Path outside the freeze	below ceiling	Reject. Extend `allowed_paths` only by a human edit, then use a new change id.
Success claim, no assertion	below ceiling	Reject. Require a failing test that names the bug before another model call.
Gate passes, process exits 0	1 to 3	Record success. Stop calling the model for this change id.
Gate passes, process exits non-zero	below ceiling	One more model call, same change id, same surface file.
Count already at ceiling	3	Stop. Revert to last known-good. Ship without the repair.

The table is the decision. A fourth suggestion, however specific it looks, is out of policy. Confidence in the prose is not evidence. The assertion, the exit status, and the process list are the evidence.

Where free model access and a free server fit

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode, as described in the operator brief for this draft, provides free model access and a free server option. Those are availability claims supplied for the article. This draft does not state a token quota, a hardware profile, a retention window, a model name, or a benchmark. Those figures were not verified against a primary source dated with this draft, and an unverified ceiling would be worse than silence.

The fit is narrow. Use the free model access for the single patch call inside the attempt ceiling. Use the free server option only to run the command frozen in surface.json. If either option changes or disappears, the gate still runs, because it never reads a vendor balance. The attempt file in git is the record of how many repairs were spent.

Keep the product out of the runtime. The host process does not import a vendor SDK for this gate. The model is a text source. The server is a place to run one command. Mixing those roles, by letting the model restart itself or open a second port for logs, is how a zero-bill afternoon becomes an unpaid operations shift.

Limitations

The marker scan misses a widened surface written through string concatenation, a new shell script, or a dependency that pulls a worker at import time. The port regex misses a bind written as a split host and port variable. The path check looks at added lines only, so a renamed file can slip through. The agreement check is a phrase list, and a patch can claim success with different wording.

Rejected patches do not increment the ceiling in this sample. The increment sits after the checks. Operators who want every model response to count, including rejects, should move the write above the marker loop. The script does not parse a unified diff properly, does not run the test suite, and does not talk to a host API.

The ceiling of three is arbitrary. A docstring typo may deserve one attempt. A charge, a login, or a deletion bug deserves zero model repairs on a free host, because a wrong side effect is not a style nit.

The gate cannot classify that risk. A human labels the change id before the first call. A dangerous id never enters the loop. Exit status still has to be captured by the operator, because this draft's wrapper replaces the shell and does not write a status file of its own.

Who should skip this

A team with a staging cluster, a review bot, and a paid error budget does not need a three-attempt file. A service that must autoscale, open extra ports, or run a queue should not pretend a one-process freeze is the architecture. Anyone who needs a measured token price, a named model, or an uptime figure should read current primary documentation before picking a host.

This draft is for a solo founder shipping one route today, willing to revert, and unwilling to let an agreeable repair invent a second runtime. The same gate can live in a pre-push hook. Readers comparing hosts can point that single in-policy patch call at MonkeyCode's free model access, keep the restart on the free server option, and treat attempts.json as the only scoreboard that matters.

Keep Health Probes Off the Model on a Free Host

Dakota Wu — Sun, 11 Oct 2026 22:16:59 +0000

A free host probes and restarts. The health route has to answer from local memory, with no model call and no disk state. That split is what lets a solo founder ship one route today and keep the bill at zero.

An AI draft often does the opposite. It puts a "model is reachable" check inside /health, adds a retry, and stores the last success in a global. The chat result looks careful. On a free server the probe runs far more often than any user request, and a restart wipes the global so the next probe fails or calls out again.

Model quality and host constraints are different problems. A sharper draft can still put a network call on the probe path. The host will not forgive that just because the draft read well in a chat window. The workflow below refuses that shape before the host starts.

The rule, in one table

The table is a local policy. It is not a vendor quota and it is not a benchmark.

Check	Ship	Stop
Health body	Fixed JSON from memory	Any fetch, SDK call, or retry
Imports in `health.py`	No network or model-SDK imports	`socket`, `urllib`, `requests`, `httpx`, or a model SDK
State	No file and no global required for a 200	Token caches, lock files, last-probe timestamps
Restart drill	Same body after kill and start	Different body, hang, or a new dependency
Model use	One draft of the business route, off the probe path	A model call inside the probe or on import

Tighten the table if the host is smaller. Do not loosen it so the probe can "just verify" the assistant.

Step 1: Put the probe in its own module

Create health.py before asking any model to draft the business route. The probe module stays hand-written. The model may touch route.py later. It does not get to edit health.py.

"""Probe handler. Unexecuted example: review before running."""

def health() -> dict:
    return {"ok": True, "deps": "none"}

Three fields would already be too many if one of them required a lookup. ok says the process is up. deps records that this ship has none.

A future route can grow. This file should not.

What the model may change

Allowed changes sit in route.py and nowhere else.

A single handler for one business path.
Pure functions that take arguments and return values, with no client construction.
Comments that restate the frozen probe rule.

Forbidden changes are a stop, even when the code compiles.

Any edit to health.py or scan_health_imports.py.
A retry, a sleep loop, or a helper whose job is to ping a model.
A new file whose name contains worker, queue, or cron.
A README line that tells the founder to add a database so the probe can look complete.

That list is the review. It takes less time than reading a generated diff that has no boundary.

Step 2: Fail the build when the probe grows a client

A source scan is blunt and useful. It reads health.py as syntax and rejects network imports. The usual generated patch adds a normal import at the top of the file, and this scan catches that shape.

Dynamic imports can slip through. That hole is listed under limits. Do not treat a green scan as a proof of isolation.

"""Import boundary for health.py. Unexecuted example."""

import ast
import pathlib
import sys

BANNED = {"socket", "urllib", "requests", "httpx", "model_sdk"}

def main() -> int:
    tree = ast.parse(pathlib.Path("health.py").read_text(encoding="utf-8"))
    bad = []
    for node in ast.walk(tree):
        if isinstance(node, ast.Import):
            names = [alias.name for alias in node.names]
        elif isinstance(node, ast.ImportFrom) and node.module:
            names = [node.module]
        else:
            continue
        for name in names:
            if name.split(".")[0] in BANNED:
                bad.append(name)
    if bad:
        print("banned imports: " + ", ".join(bad))
        return 1
    print("health imports ok")
    return 0

if __name__ == "__main__":
    raise SystemExit(main())

Replace model_sdk with the import root of whatever client the draft actually used. The placeholder is not a product name.

python3 scan_health_imports.py

A nonzero exit stops the ship. Do not add the banned name to an allow list in the same hour the draft suggested it. That is the patch asking for a second design.

Step 3: Assert that a call does not touch the network

The scan cannot see a helper, imported from route.py, that opens a socket. A tiny test covers the runtime path. The example expects pytest and monkeypatch. It stays an unexecuted example until it runs in a clean virtualenv.

"""Runtime boundary. Unexecuted example."""

import socket
import urllib.request

import health

def test_health_makes_no_network(monkeypatch):
    def boom(*_args, **_kwargs):
        raise AssertionError("health opened the network")

    monkeypatch.setattr(socket, "socket", boom)
    monkeypatch.setattr(urllib.request, "urlopen", boom)
    assert health.health() == {"ok": True, "deps": "none"}

python3 -m pytest -q test_health.py

The assertion is the contract. If a later edit needs a database check before it can return 200, this test should fail and the ship should wait. A solo free host is the wrong place to invent a dependency probe.

Step 4: Kill the process and demand the same body

Free hosts restart. Some sleep when traffic stops. This draft claims neither a sleep timer nor a memory cap nor an uptime figure, because none of those were measured here. The local drill proves a weaker fact: the probe does not need a global that the process just lost.

"""Local probe server. Unexecuted example."""

import json
from http.server import BaseHTTPRequestHandler, HTTPServer

import health

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path != "/health":
            self.send_response(404)
            self.end_headers()
            return
        body = json.dumps(health.health()).encode()
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

    def log_message(self, *_args):
        return

if __name__ == "__main__":
    HTTPServer(("127.0.0.1", 8080), Handler).serve_forever()

python3 probe_server.py &
PID=$!
sleep 0.3
curl -fsS --max-time 2 http://127.0.0.1:8080/health > /tmp/h1.json
kill "$PID"
wait "$PID" 2>/dev/null || true
python3 probe_server.py &
PID=$!
sleep 0.3
curl -fsS --max-time 2 http://127.0.0.1:8080/health > /tmp/h2.json
kill "$PID"
cmp /tmp/h1.json /tmp/h2.json

cmp is the promotion check. A mismatch means the route rebuilt state, called something, or changed shape across a restart. Fix that on the laptop. Do not debug it after the host has started probing.

Step 5: Read the failure, then stop

Each failed check has one repair. A second repair in the same pass usually means the design grew a new service.

Exit signal	Meaning	Next action
Scan exit 1	`health.py` imported a banned root	Delete the import. Do not wrap it in a helper
Pytest failure	`health()` reached `socket` or `urlopen`	Remove the call. The monkeypatch is doing its job
Curl timeout	Nothing accepted connections on `127.0.0.1:8080`	Fix the bind. Do not raise `--max-time`
`cmp` difference	The body depends on process lifetime	Return the constant dict again

Write the failing signal into the commit message, then stop for the day if the repair is not the one in that row. Shipping around a red check is how a free host starts a bill.

Step 6: Use a free model on the route, never on the probe

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

The operator describes MonkeyCode as an open-source coding assistant with free model access and a free server option. Those availability claims are operator-supplied. This draft does not name a model, state a token quota, describe hardware, or treat either option as permanent.

Confirm the project page on ship day. If either claim is gone, keep the health split and skip the product. The three local commands still decide the ship.

Use the free model, when it is actually available, for one draft of route.py only. Paste a line that health.py is frozen. Discard a reply that edits the probe, adds a retry, or imports a client into the health module. Then run the scan, the test, and the restart drill again. The model does not promote the ship. The commands do.

The free server, when it is actually available, is where the already-tested process runs. Copy the probe module, the app entry, and the business route. Leave add-ons, cron, and a database toggle off.

A probe that stays local is what keeps that host from calling a model on every platform check. Point the host health setting at /health only after the local cmp succeeded.

Limits, and who should ignore this

The scan misses importlib and clients hidden behind a string. The test misses a network call that happens only when a host environment variable is set. The restart drill uses localhost and a short sleep. It does not reproduce disk quotas, TLS, or a real idle policy.

No latency number in this article is a measurement. No token total is stated, because none was verified for this draft. Founders who need a current quota should read the project page themselves and treat this workflow as the constraint, not as a pricing page.

A team whose health check must fail closed when a database is down should not adopt this probe. Their users need a dependency signal. A product that already has a paid host and a scheduler should not pretend a three-command drill is an operations platform.

This pattern is for a solo founder shipping one route, accepting a dull health body, and refusing extra moving parts until a bill is a choice. Run the scan, the test, and the restart cmp in that order. Ship only if all three pass, and leave the probe file out of the model session.

Pin a Solo Waitlist to a Local Byte and Time Ceiling

Dakota Wu — Sat, 10 Oct 2026 18:54:27 +0000

A solo waitlist can ship today and still keep the bill at zero. That result holds only when the handler, the store, and a local request-budget harness agree before any public host exists. A free model may draft the next check. It may not widen the response, add a client, or invent a second process.

The method is small on purpose. One POST, one append-only file, one command that fails closed. Everything else waits.

The constraint that makes the route shippable

MonkeyCode's free model access and a free server option are the two availability claims this workflow relies on. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Neither claim is a hardware spec, a duration, or a numeric token quota. This article does not treat quota, region, disk, or uptime figures as stable, because those numbers go stale faster than a tutorial can be corrected. The founder reads the current console before counting on either option.

The local ceiling stays stricter than any assumed platform limit. If the console no longer shows a free path, the harness still stops a quiet dependency from landing in the tree.

Where the second edit usually breaks the bill

The first generated handler is often short. The second prompt is the risky one. Asked to make a waitlist nicer, a model will echo the stored email, wrap the write in a retry, or pull in a helper that opens a socket.

The diff can look harmless. The response gets fatter, the call gets slower, or a new import appears below the fold. A ceiling on bytes and milliseconds catches the first two failures. It does not catch every import, which is why the founder still reads the diff after the command goes green.

Files that are allowed to exist

The layout is the policy. Extra services do not get a folder.

waitlist/
  handler.py
  budget.env
  fixtures/ok.json
  fixtures/fat.json
  harness.sh

store.ndjson is created at runtime and is never committed. budget.env is committed. It records founder policy, not a measured host SLA.

# budget.env — local policy, not a vendor measurement
MAX_RESPONSE_BYTES=1024
MAX_HANDLER_MS=200
ALLOWED_METHOD=POST
ALLOWED_PATH=/waitlist

Two hundred milliseconds is a laptop ceiling. It forces the handler to stay cheap before a cold remote process is involved. It is not a claim about any free server timeout, and this article publishes no host timing because none was measured here.

Step 1. Pin the handler to the standard library

The handler checks the method, the path, and one email field. It appends one JSON line and returns a tiny body. No framework, no mail client, and no socket of its own.

# handler.py — proposal, not executed for this article
import json
from pathlib import Path

STORE = Path("store.ndjson")

def handle(method, path, raw, budget):
    if method != budget["ALLOWED_METHOD"] or path != budget["ALLOWED_PATH"]:
        return 405, b'{"error":"method_or_path"}\n'
    try:
        body = json.loads(raw)
    except json.JSONDecodeError:
        return 400, b'{"error":"json"}\n'
    email = body.get("email")
    if not isinstance(email, str) or "@" not in email or len(email) > 120:
        return 400, b'{"error":"email"}\n'
    if len(raw) > 512:
        return 400, b'{"error":"size"}\n'
    line = json.dumps({"email": email}, separators=(",", ":")) + "\n"
    with STORE.open("a", encoding="utf-8") as fh:
        fh.write(line)
    return 201, b'{"ok":true}\n'

The snippet is a proposal. It does not hash the address, rate-limit callers, or prove the mailbox exists. Those omissions are deliberate. A day-one route that adds them usually reaches for a paid API before the first real signup arrives.

Step 2. Add fixtures that stand in for a bad edit

Two fixtures are enough for the first gate. The good one is a short object. The fat one is a large object that must be rejected before the store grows.

mkdir -p fixtures
printf '%s\n' '{"email":"ada@example.com"}' > fixtures/ok.json
printf '%s' '{"email":"ada@example.com","pad":"' > fixtures/fat.json
python3 -c 'print("x" * 800, end="")' >> fixtures/fat.json
printf '%s\n' '"}' >> fixtures/fat.json

The fat fixture is not a fuzz corpus. It stands in for the edit that echoes user input into a long error body, or that accepts a blob because a prompt said to store the raw request. If that edit lands, the gate should fail before any copy to a host.

Step 3. Run the budget command on the laptop

The harness imports the handler in-process. It does not bind a port, and it does not call a network. Startup noise stays out of the ceiling, which keeps the gate readable. Values in budget.env must not contain spaces around =, because the shell sources the file directly.

#!/bin/sh
# harness.sh — local gate, not a load test
set -eu
set -a
. ./budget.env
set +a
rm -f store.ndjson

python3 - <<'PY'
import os, time, pathlib, importlib.util
spec = importlib.util.spec_from_file_location("handler", "handler.py")
mod = importlib.util.module_from_spec(spec)
spec.loader.exec_module(mod)
budget = {
    "ALLOWED_METHOD": os.environ["ALLOWED_METHOD"],
    "ALLOWED_PATH": os.environ["ALLOWED_PATH"],
}
max_bytes = int(os.environ["MAX_RESPONSE_BYTES"])
max_ms = int(os.environ["MAX_HANDLER_MS"])
cases = [
    ("POST", "/waitlist", pathlib.Path("fixtures/ok.json").read_bytes(), 201),
    ("POST", "/waitlist", pathlib.Path("fixtures/fat.json").read_bytes(), 400),
    ("GET", "/waitlist", b"{}", 405),
]
for method, path, raw, expect in cases:
    t0 = time.perf_counter()
    status, body = mod.handle(method, path, raw, budget)
    elapsed = (time.perf_counter() - t0) * 1000
    if status != expect or len(body) > max_bytes or elapsed > max_ms:
        raise SystemExit(
            "fail method=%s status=%s bytes=%s ms=%.1f"
            % (method, status, len(body), elapsed)
        )
print("budget-ok")
PY

The release command is short.

chmod +x harness.sh
./harness.sh

The script prints budget-ok only when every case matches. In this proposal that string is the release token, not a measurement from a live host. Any other output means the files stay on the laptop.

The founder does not repair a red run by raising MAX_RESPONSE_BYTES inside the same edit that grew the body. The ceiling moves in a separate commit, with a one-line reason, or it does not move.

Step 4. Let the model draft, then restore on red

The free model earns its place as a drafter inside this fence, not as the reviewer of record. The prompt includes budget.env, handler.py, and one requested change, such as rejecting a missing source label without new imports. The reply is pasted over a copy of the handler by hand. Nothing is applied by a tool.

cp handler.py handler.py.bak
# paste the drafted handler over handler.py, then:
./harness.sh || mv handler.py.bak handler.py

There is no second model call in the loop. A green harness is necessary and not sufficient. The founder still scans the import block. A new network client can be fast and small, so the byte ceiling will not save a route that starts calling out.

Step 5. Copy the green tree, and stop there

Upload is a copy of handler.py and budget.env. It is not a database create, a queue bind, or a domain purchase. If the free server option wants a start command, that command should import the same module the harness imported. A framework entrypoint suggested in a model comment is a new service, and it stays off the host.

# DEST comes from the current panel, not from this article
test -n "${DEST}"
cp handler.py budget.env "${DEST}/"

This article names no region, disk size, or process limit. A copied number would be worse than a blank. Consoles change, and a stale limit gets treated as permission.

How to judge the second edit

Suggested edit	What the gate sees	Action
Tighter email check, no new import	`budget-ok`	Keep
Error body echoes the stored line	Byte ceiling fails	Revert
Retry wrapped around the file write	Time ceiling fails, or the gate hangs	Revert
New HTTP client import	Often still green	Reject in the diff read
Paid mail API for confirmation	Out of policy even if fast	Reject before the harness

The last two rows are the honest limit of a local timer. Speed is not the same thing as a zero bill. A fast call to a paid API is still a bill.

Limits that stay even after a green run

The timer measures the laptop. A free server can be slower when the process is cold, and no cold-start figure is claimed here. A local pass does not prove a remote pass.

The store is one append-only file. Two overlapping writes can tear a line. That is tolerable for a solo list with tiny traffic. It is the wrong store for a paid signup, or for two people sharing a host.

The email check is a length cap plus an @ sign. Junk will get in. Mail will not go out. Confirmation mail, abuse controls, and a privacy review are a different system, and that system should be expected to cost money.

The harness does not watch DNS, TLS, or an idle policy on the host. A route can pass locally and still sleep after upload. The founder opens the public URL once. If the panel asks for a card, the upload stops.

Who should leave this pattern alone

More than one writer should not share store.ndjson. A product that takes payment should not keep emails this way. A founder who will not read a diff should not aim a free model at the handler, because quiet imports slip past the timer.

Anyone who needs a stated uptime target should not treat a free server option as capacity. The option is a way to put one route on the public internet today, with the limits written in budget.env. It is not a promise that the option remains.

After the command prints budget-ok

A founder who already keeps this fence can draft the next tiny check with MonkeyCode's free model access, and can use the free server option as the only copy target, if the console still shows both. The release rule does not change with the editor. ./harness.sh prints budget-ok, or the files stay on the laptop.

A Cold-Start Ledger for Shipping One Indie Route on a Free Server

Dakota Wu — Thu, 08 Oct 2026 10:53:05 +0000

A solo API earns a free-server deploy only when process startup does no network I/O, starts no thread, and writes nothing that must survive the process. That rule is the shipping decision. A warm laptop hides violations, because the process never sleeps and the disk never disappears. This ledger fails the ship on the founder's machine before a free host or a free-model retry pays for the mistake.

The check is local and cheap. It reads Python files, walks the syntax tree, and returns a non-zero status when module-level code calls a network client, starts a worker, or opens a path outside an allowed temp prefix. The script in this article is an unexecuted example. The founder should run it, read every hit, and keep judgment over lines the scanner cannot see.

Where the free path actually breaks

Indie drafts often import a client and call it at the top of the file so a sample looks ready. The first request on a laptop is fast, because that import already happened an hour ago. A free server that sleeps must import again on wake, and the import now sits inside the visitor's timeout.

Disk is the second break. A SQLite file beside the source tree looks like a zero-cost database until the platform discards the filesystem. The repair loop is the third break. A timed-out route sends the founder back to a coding assistant, and the easiest patch is a paid broker, a hosted queue, or a box that never sleeps.

None of those patches belong in a ship-today plan. The ledger exists so the route stays small enough that a free path is still an honest choice.

1. Freeze the budget in a file

Policy stays in coldstart-budget.json at the project root. The values are local choices for this app, not a vendor quota and not a measured latency.

{
  "scan_roots": ["app"],
  "forbidden_import_roots": ["requests", "httpx", "socket", "urllib", "boto3", "stripe"],
  "forbidden_suffixes": ["Thread", "Popen", "create_connection"],
  "allowed_write_prefixes": ["/tmp/", "./tmp/"]
}

A listed root may be imported. Calling that root while the module loads is the defect the ledger rejects. Importing requests is ordinary, while calling requests.get at import time is not. The scan root stays on app, not on a virtualenv, or third-party packages will flood the report.

2. Keep one bad file and one good file

The bad module calls the network while Python is still loading it. A sleeping host repeats that call on every wake.

# app/bad_health.py — should fail the ledger
import requests

READY = requests.get("https://example.invalid/health", timeout=2).status_code

The good module binds a function and stops. Work starts only after a request handler calls that function.

# app/health.py — should pass the ledger
import requests

def health():
    response = requests.get("https://example.invalid/health", timeout=2)
    return response.status_code

example.invalid is a reserved documentation name, not a live host. The samples exist so the scanner has one file to reject and one file to accept. They are not a production probe, and the founder should not point them at a customer domain.

3. Scan import-time calls

Save the following as coldstart_ledger.py. It uses the Python standard library only, so a fresh laptop can run it without a package install. Treat it as an unexecuted example until the founder has run it on a copy of the tree.

#!/usr/bin/env python3
"""Unexecuted example: flag import-time network, thread, and unsafe file writes."""

import ast
import json
import sys
from pathlib import Path

def dotted(node):
    if isinstance(node, ast.Name):
        return node.id
    if isinstance(node, ast.Attribute):
        head = dotted(node.value)
        return f"{head}.{node.attr}" if head else node.attr
    return ""

def inside_function(stack):
    kinds = (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)
    return any(isinstance(item, kinds) for item in stack)

class Ledger(ast.NodeVisitor):
    def __init__(self, path, budget, findings):
        self.path = path
        self.budget = budget
        self.findings = findings
        self.stack = []

    def generic_visit(self, node):
        self.stack.append(node)
        super().generic_visit(node)
        self.stack.pop()

    def visit_Call(self, node):
        if not inside_function(self.stack):
            name = dotted(node.func)
            root = name.split(".")[0]
            suffix = name.split(".")[-1]
            blocked_root = root in self.budget["forbidden_import_roots"]
            blocked_suffix = suffix in self.budget["forbidden_suffixes"]
            if blocked_root or blocked_suffix:
                line = f"{self.path}:{node.lineno}: import-time call {name}"
                self.findings.append(line)
            self._check_open(node, suffix)
        self.generic_visit(node)

    def _check_open(self, node, suffix):
        if suffix != "open" or not node.args:
            return
        arg = node.args[0]
        if not isinstance(arg, ast.Constant) or not isinstance(arg.value, str):
            self.findings.append(f"{self.path}:{node.lineno}: non-literal open() at import")
            return
        prefixes = tuple(self.budget["allowed_write_prefixes"])
        if not arg.value.startswith(prefixes):
            self.findings.append(f"{self.path}:{node.lineno}: write outside temp ({arg.value})")

def main():
    budget_path = Path("coldstart-budget.json")
    budget = json.loads(budget_path.read_text(encoding="utf-8"))
    findings = []
    for root in budget["scan_roots"]:
        base = Path(root)
        if not base.exists():
            findings.append(f"missing scan root: {root}")
            continue
        for path in base.rglob("*.py"):
            source = path.read_text(encoding="utf-8")
            tree = ast.parse(source, filename=str(path))
            Ledger(path, budget, findings).visit(tree)
    if findings:
        print("\n".join(findings))
        return 1
    print("cold-start ledger: no import-time calls flagged")
    return 0

if __name__ == "__main__":
    sys.exit(main())

Function bodies are ignored on purpose. A call inside health is request work, and request work is allowed. A call in the module body, including a call hiding in __init__.py, is startup work. Startup work is what a cold free server repeats for every wake.

4. Run the ledger before any host is chosen

The ledger must run as its own process. Importing the app inside the same interpreter would pay the cold-start cost the check is meant to catch. From the project root, with app/bad_health.py still present, the expected result is a failure.

python3 -m py_compile coldstart_ledger.py
python3 coldstart_ledger.py
echo "ledger_exit=$?"

A failing run prints a path, a line number, and the call name, then exits 1. Moving the call into a function, or removing bad_health.py from app/, should print cold-start ledger: no import-time calls flagged and exit 0. If the status stays 1, the founder reads the printed line instead of guessing. A syntax error aborts with a traceback, so that file gets fixed locally and the ledger runs again before any deploy command exists.

5. Spend free model access on one flagged file

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode fits this workflow in two optional places, and nowhere else. Free model access can rewrite a single flagged file so the network call moves inside a handler and keeps a timeout. The free server option is a destination for the route after the ledger exits 0, not a reason to skip the ledger. This draft treats those two availability claims as operator-supplied and current. It names no model, no token allowance, no machine size, and no duration, because those facts move and a post should not freeze them.

The same-day read is part of the method. Before either free option is used, the founder opens the current plan notes and checks that model access is still free, that a no-charge server plan is still offered, and that sleep, disk, and request limits still match this route. If the notes disagree with this article, the notes win.

The assistant prompt stays narrow. It asks for the import-time call to move into a function, for a timeout on the outbound request, and for no new host, queue, or database. After the edit, the ledger runs again. A green scan plus a new paid hostname is still a failed ship. The scanner does not understand pricing. The founder does.

6. Map the exit status to a ship decision

The table is the deploy policy for the day. It assumes nothing about a vendor's future pricing.

Ledger result	Same-day action
Exit 0, and the diff adds no external host	Deploy that one route and watch the first cold request
Exit 1, with one import-time call	Rewrite that call, re-run, then decide
Exit 0, but the route needs a worker or durable disk	Keep the route off the free server
Assistant patch adds a broker or SMTP host	Reject the patch and stay on the laptop
Scanner raises SyntaxError	Fix the file locally; do not deploy around the crash

The first cold request remains a manual check. The ledger cannot see the platform's real wake time. The founder calls the route once after an idle period, confirms a response, and only then shares the URL.

Limits, and who should leave the free path

The scanner is a syntax screen, not a proof of safety. It misses exec, string-built imports, and calls assembled with getattr. A non-literal open() is reported as review work, not classified as safe. A green run is not a load test, not a secret scan, and not evidence that a free tier will still exist next month.

Some products should not use this approach at all. A websocket that must stay connected, a billing job that must run while nobody is browsing, and any personal-data store that lives only on local disk do not fit a host that may sleep or wipe files. A team that needs a stated uptime commitment needs a plan that actually states one. This ledger will not create that commitment.

Another assisted rewrite will not repair those mismatches. Spending a free model turn to paper over a sleeping host burns the allowance and leaves the route wrong. The honest outcome is a smaller route, or a paid host chosen in the open.

Close the loop on one route

The founder selects one read-only route, runs the ledger, and ships that route only when startup stays quiet. Every other route waits. That restraint is what keeps today's bill at zero.

A founder who wants help with the rewrite can point MonkeyCode's free model access at the single flagged file, re-run the ledger, and confirm the free-server notes before any deploy command. The ledger, not the assistant, decides whether the route may leave the laptop.

One Model Call Per Delivery With a File Outbox

Dakota Wu — Thu, 08 Oct 2026 08:33:52 +0000

A solo webhook ships today only when the retry path cannot create a bill. One process and a local file can hold a demo. An AI patch that adds a broker, a hosted cache, or a fresh model call on every timeout cannot.

Cap the work in the repo first. Then publish the route. That order is the method, and it is stricter than a prompt that says "keep it cheap."

A public demo page is cheap to generate. The signup webhook behind it is where cost and retries hide. Host allowlists and recorded fixtures solve different failures. This note covers one delivery, one model call, and a file that remembers both after a restart.

Where the draft spends money

Generated handlers fail in a predictable shape. The route accepts a POST, a timeout fires, and a loop calls the model again. A second edit imports a queue client so the loop can be "more reliable." A third edit reads a region variable that a single process never needed.

Short patches. Large bills. The shape is the same even when the wording changes.

Three checks catch it before merge.

The HTTP handler writes an event file and returns. It does not call a model.
A later step may call the model once, then stores the result beside the event.
A retry loads the stored result. It does not get another model call, and it does not require a broker, a hosted cache, or a worker fleet.

If a draft cannot pass those checks, the feature waits. The founder does not upgrade hosting to rescue the draft.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. Free model access is relevant only as a drafting aid on the founder's laptop. The free server is relevant only as a place to run the fixture-backed process after the tests pass. Quotas, hardware, duration, model names, and permanence are omitted on purpose. No primary source for those figures was attached to this draft, and an unchecked numeric allowance should not be published as current fact.

Day-one decision table

Read the table before opening the generated diff. The Allow column is the cost class for today. The Reject column is what a helpful draft will often suggest. Take the Allow cell, or cut the job.

Job	Allow on day one	Reject on day one	Why
Accept a signed POST	One process, one port	Managed gateway	A single host can bind a port
Survive restart	Append-only JSON files	Paid queue or hosted cache	A file is enough for a solo demo
Stop double effects	Idempotency key in the file	External lock service	The key travels with the event
Classify the payload	One model call, then store it	Model call per retry	Retries must stay free
Prove the route	Fixture double, no socket	Live model calls in CI	CI must not drain an allowance
Notice failure	Log line and non-zero exit	Paid paging vendor	A founder can read a log today

A row that cannot be done in the Allow column is out of scope for this ship. That is a product cut, not a hosting upgrade.

Five steps, in order

The steps are mechanical. A comment in the pull request is not a substitute for any of them. Run them on the laptop before the free server sees the tree.

1. Pin the cost class

Write a one-line file and commit it. The preflight fails if that line changes.

printf 'zero\n' > cost_class.txt
git add cost_class.txt

The pin is dull on purpose. Dull controls survive a rushed afternoon better than a paragraph of review notes.

2. Split accept from classify

accept hashes the body, writes JSON, and returns. classify runs later. It increments a counter only when the result is empty, and it refuses to pass a budget of one.

# Proposal. Not run against a live host for this article.
import hashlib
import json
from pathlib import Path

ROOT = Path("outbox")
BUDGET = 1

def event_id(raw: bytes) -> str:
    return hashlib.sha256(raw).hexdigest()[:16]

def accept(raw: bytes) -> dict:
    ROOT.mkdir(exist_ok=True)
    eid = event_id(raw)
    path = ROOT / f"{eid}.json"
    if path.exists():
        return json.loads(path.read_text())
    record = {
        "id": eid,
        "body": raw.decode("utf-8"),
        "model_calls": 0,
        "result": None,
    }
    path.write_text(json.dumps(record))
    return record

def classify(eid: str, model) -> dict:
    path = ROOT / f"{eid}.json"
    record = json.loads(path.read_text())
    if record["result"] is not None:
        return record
    if record["model_calls"] >= BUDGET:
        raise RuntimeError("model budget exhausted")
    record["model_calls"] += 1
    record["result"] = model(record["body"])
    path.write_text(json.dumps(record))
    return record

The HTTP route may import accept only. A draft that calls classify inside the request function has already broken the budget, even if the import scanner is quiet.

3. Scan the diff for brokers

Keep the banned list local and short. Add a word only after a real draft uses it. The CLI below is the merge gate.

# Proposal scanner and CLI. Unexecuted example.
import sys
from pathlib import Path

BANNED = ("boto3", "sqs", "redis", "amqp", "celery", "kafka", "pubsub")

def scan(diff_text: str) -> list[str]:
    hits = []
    for line in diff_text.splitlines():
        if not line.startswith("+") or line.startswith("+++"):
            continue
        low = line.lower()
        for word in BANNED:
            if word in low:
                hits.append(word)
    return sorted(set(hits))

def cost_ok(text: str) -> bool:
    return text.strip() == "zero"

def main(argv: list[str]) -> int:
    if "--diff" not in argv or "--cost-class" not in argv:
        return 2
    diff_path = argv[argv.index("--diff") + 1]
    class_path = argv[argv.index("--cost-class") + 1]
    hits = scan(Path(diff_path).read_text())
    if hits or not cost_ok(Path(class_path).read_text()):
        print("rejected", ",".join(hits))
        return 2
    print("accepted")
    return 0

if __name__ == "__main__":
    raise SystemExit(main(sys.argv[1:]))

python preflight.py --diff changes.diff --cost-class cost_class.txt
echo "preflight_exit=$?"

Exit 0 means no banned import and a zero cost class. Exit 2 stops the merge. Do not override that exit because the patch looks small.

4. Prove the retry with a double

The test model counts calls. The second classify must not increment that count. Any drafting session, including one that uses MonkeyCode's free model access, stays outside this process. The test should pass on a laptop with the network disabled.

# Proposal test. Unexecuted example.
def test_second_classify_is_free(tmp_path, monkeypatch):
    monkeypatch.chdir(tmp_path)
    calls = {"n": 0}

    def model(body: str) -> str:
        calls["n"] += 1
        return "ok"

    payload = "{'type':'signup'}"
    rec = accept(payload.encode("ascii"))
    classify(rec["id"], model)
    again = classify(rec["id"], model)
    assert calls["n"] == 1
    assert again["result"] == "ok"

python -m unittest test_outbox.py -v

A failure here is a stop. Do not deploy a red tree to the free server to see what happens.

5. Boot fixtures, then one manual POST

Start with fixtures on. Confirm the health payload. Then send one real body from the founder's machine and read the outbox file. A missing file, a second model call, or a new import means roll back the process. It does not mean rewrite the cost class.

# Proposal health payload. Unexecuted example.
def health() -> dict:
    klass = Path("cost_class.txt").read_text().strip()
    return {"cost_class": klass, "model_calls": 0, "fixtures": True}

FIXTURES=1 python app.py
curl -fsS http://127.0.0.1:8080/health

Health should report a zero cost class and zero model calls before that manual POST. After the POST, the matching JSON file should show a model call count of 0 or 1, never 2.

Failure analysis

Four breaks are worth drilling before the route is public. Each one has the same response. Name it, keep the cost class, and cut scope.

Disk wipe comes first. A free server may drop local files on restart or redeploy. The outbox then forgets idempotency keys. Treat the demo as disposable, or wait until a durable disk is actually available. Do not fix a wipe by adding a hosted cache in the same patch.

Two processes are the second break. They will race on one directory. This design allows one process. A second instance is a new design, not a config flag, and it is outside the day-one table.

The truncated id is the third break. Sixteen hex characters are enough for a solo demo, not for a high-volume bus. If volume grows, lengthen the id. A paid lock service is not the first response to a short hash.

The fourth break is a crash after the counter increments and before the result is stored. The sample spends the budget and stores nothing. That is fail-closed. A founder who needs to retry a failed call must add an explicit error field and a separate rule. Silent re-entry into another model route is not that rule.

The free server is not a puzzle to outsmart. When a break shows up, the ship gets smaller.

Who should not use this

Skip the file outbox when more than one instance must run, when the payload is regulated data, or when a missed file is an unacceptable loss. Also skip it when the side effect cannot be stored and replayed. A zero-bill demo is not a compliance design, and free model access is not a throughput commitment.

Operators who need fan-out, multi-region delivery, or a retention guarantee should buy the queue and write that choice into the cost class file. Pretending a free process can imitate that stack wastes the afternoon this method is meant to save.

The next patch

Run the scanner on the diff before reading the generated explanation. If the scanner is empty and the unit test still shows one model call, the tree can move to the free server in fixture mode. If a broker import appears, delete the import and keep the file. Hosting does not get a vote until those two checks agree.

Founders who draft with MonkeyCode's free model access can run that same unittest on the laptop tree and again on the free-server checkout. Ship only when both call counts match. That comparison is the check worth keeping. Whatever the allowance is this week, it is not a design input.

Reject Remote Schema Refs Before a Solo API Ships

Dakota Wu — Thu, 24 Sep 2026 22:05:03 +0000

A solo founder can ship an AI-drafted HTTP API on the same day the idea appears and still keep the infrastructure bill at zero. The gate is local. It rejects remote schema references, rejects any servers host outside a loopback allowlist, and rejects documented examples that exceed a fixed byte cap. The check ends before a process opens a socket, and before a free-tier prompt is spent proving what a file already knows.

Surprise cost starts in the contract, not in the cloud console. A drafting session asked to complete the API will often insert an https:// $ref, a hosted mock, or a bulky example copied from a vendor page. The editor still looks offline. The next resolver does not.

The bill hides in three fields

Remote $ref values fail in two directions. Offline, the laptop cannot fetch the schema, so the build breaks on a train. Online, the fetched host can add a key, a quota wall, or a paid tier without any change to application code. A root-local #/components/... reference stays inside one file. That is the reproducible choice.

servers is the second leak. One URL aimed at a metered mock, a gateway, or a vendor sandbox invents a host the founder never priced. Loopback is enough to ship today. A public base URL can live in a second file that is not the cost boundary this gate enforces.

Example payloads are the third leak. Large samples burn time, context, and any free request allowance long before the handler exists. A hard cap on example bytes keeps the contract small enough to reread. The 2048-byte number in the proposal is local policy. It is not a measured limit of any hosted plan.

Clear failures matter more than clever ones. Each error line names the JSON path and the rule that fired. A founder debugging at midnight should not have to infer whether the gate disliked a host, a ref, or a missing operationId.

Decision table

Spec signal	Gate	Why it matters on a zero bill
`$ref` starts with `http://`, `https://`, or `//`	Reject	Resolution can bill or break offline
`$ref` starts with `#/`	Allow	Stays inside the same JSON file
Any other `$ref`	Reject	File-relative refs wander across directories
`servers[].url` is `http` on `127.0.0.1` or `localhost`	Allow	Same-day loopback only
Any other server host or scheme	Reject	Stops an invented paid host
JSON size of an `example` over 2048 bytes	Reject	Keeps samples small enough to reread
Path operation missing `operationId`	Reject	Fixtures need a stable name
URL mentioned only in `description`	Allow	Prose is not a fetch

Steps

1. Freeze the allowlist before any draft

Write allowed hosts into the checker, not into a chat log. Two names are enough on day one: 127.0.0.1 and localhost. A longer list is a product decision. It should arrive as a reviewed diff, not as a model suggestion that a sandbox would be more realistic.

2. Demand OpenAPI JSON

The Python standard library parses JSON. It does not parse YAML. A zero-install gate should refuse a spec that needs a third-party parser before it can be trusted. Ask the drafting session for JSON only. Treat a YAML blob as unfinished, even if the prose is polished.

3. Run the budget gate

Save the proposal as spec_budget.py. Exit status 0 means the file may stay in the repo. Any other status means the spec does not leave the laptop. Do not override the gate to unblock a demo.

4. Bind one fixture to each operationId

Coverage here is a name check, not a live call. A fixture file maps operationId to a path and a status code. Missing names fail the binder. Recording fixtures by clicking a hosted mock would spend the budget this workflow refuses to open.

5. Smoke-test loopback, or stop

Start the founder's own process on 127.0.0.1 when that process exists. Cap the probe at two seconds. If the handler is not written yet, ship the spec, the gate, and the fixture binder. Those three files are a complete same-day result. A staging cluster is not part of the definition of done.

Same-day file set

A same-day ship, under this method, is four files and two commands. openapi.json holds the contract. spec_budget.py enforces the table. bind_fixtures.py checks names. fixtures.json stores path and status only. No container registry, no remote state, and no secret store is required to call the work finished.

That definition will feel small to a team with a platform group. It is the point. A solo founder who adds a hosted log drain just for the demo has already left the zero-bill path. Add that drain later, in a diff that names the host on purpose.

Proposal checker

This script is an unexecuted proposal. It was not run against a live account, and it claims no timing result. Python 3.9 or newer is assumed. No third-party package is imported.

#!/usr/bin/env python3
'''Local OpenAPI budget gate. Proposal only; not executed for this article.'''

import json
import sys
from urllib.parse import urlparse

ALLOWED_HOSTS = {'127.0.0.1', 'localhost'}
MAX_EXAMPLE_BYTES = 2048
HTTP_METHODS = {
    'get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace',
}

def fail(errors):
    for item in errors:
        print(f'spec-budget: {item}', file=sys.stderr)
    return 1 if errors else 0

def walk(node, path, errors):
    if isinstance(node, dict):
        ref = node.get('$ref')
        if isinstance(ref, str):
            if ref.startswith(('http://', 'https://', '//')):
                errors.append(f'{path}: remote $ref blocked: {ref}')
            elif not ref.startswith('#/'):
                errors.append(
                    f'{path}: only root-local #/ refs are allowed: {ref}'
                )
        if 'example' in node:
            try:
                encoded = json.dumps(
                    node['example'], separators=(',', ':')
                ).encode('utf-8')
            except TypeError:
                errors.append(f'{path}: example is not JSON-serializable')
            else:
                size = len(encoded)
                if size > MAX_EXAMPLE_BYTES:
                    errors.append(
                        f'{path}: example is {size} bytes; cap is {MAX_EXAMPLE_BYTES}'
                    )
        for key, value in node.items():
            walk(value, f'{path}.{key}', errors)
    elif isinstance(node, list):
        for index, value in enumerate(node):
            walk(value, f'{path}[{index}]', errors)

def check_servers(doc, errors):
    servers = doc.get('servers')
    if not isinstance(servers, list) or not servers:
        errors.append('servers: at least one loopback URL is required')
        return
    for index, server in enumerate(servers):
        url = server.get('url') if isinstance(server, dict) else None
        parsed = urlparse(url or '')
        if parsed.scheme != 'http' or parsed.hostname not in ALLOWED_HOSTS:
            errors.append(
                f'servers[{index}]: only http loopback is allowed, got {url!r}'
            )

def check_operation_ids(doc, errors):
    paths = doc.get('paths')
    if not isinstance(paths, dict) or not paths:
        errors.append('paths: at least one path is required')
        return
    for path, item in paths.items():
        if not isinstance(item, dict):
            errors.append(f'paths.{path}: expected an object')
            continue
        for method, op in item.items():
            if method.lower() not in HTTP_METHODS or not isinstance(op, dict):
                continue
            if not op.get('operationId'):
                errors.append(f'paths.{path}.{method}: missing operationId')

def main():
    if len(sys.argv) != 2:
        print('usage: spec_budget.py openapi.json', file=sys.stderr)
        return 2
    with open(sys.argv[1], encoding='utf-8') as handle:
        doc = json.load(handle)
    if not isinstance(doc, dict):
        print('spec-budget: root must be an object', file=sys.stderr)
        return 1
    errors = []
    check_servers(doc, errors)
    check_operation_ids(doc, errors)
    walk(doc, '$', errors)
    return fail(errors)

if __name__ == '__main__':
    raise SystemExit(main())

The illustration below should fail. It is synthetic. It is not a captured third-party document.

{
  "openapi": "3.0.3",
  "info": {"title": "demo", "version": "0.0.1"},
  "servers": [{"url": "https://mock.example.test/v1"}],
  "paths": {
    "/health": {
      "get": {
        "responses": {
          "200": {
            "description": "ok",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "https://schemas.example.test/Health.json"
                }
              }
            }
          }
        }
      }
    }
  }
}

Commands to keep next to the script:

python3 spec_budget.py openapi.json
printf 'gate_exit=%s\n' "$?"
curl --fail --silent --show-error --max-time 2 http://127.0.0.1:8080/health

The curl line assumes a local process the founder already chose to start. Nothing in this article records a live response from that command.

Proposal fixture binder

The binder is also unexecuted. It only checks that every operationId has a row. It does not send HTTP.

#!/usr/bin/env python3
'''Fixture name binder. Proposal only; not executed for this article.'''

import json
import sys

HTTP_METHODS = {
    'get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace',
}

def main():
    if len(sys.argv) != 3:
        print('usage: bind_fixtures.py openapi.json fixtures.json', file=sys.stderr)
        return 2
    with open(sys.argv[1], encoding='utf-8') as handle:
        spec = json.load(handle)
    with open(sys.argv[2], encoding='utf-8') as handle:
        fixtures = json.load(handle)
    missing = []
    for path, item in (spec.get('paths') or {}).items():
        if not isinstance(item, dict):
            continue
        for method, op in item.items():
            if method.lower() not in HTTP_METHODS or not isinstance(op, dict):
                continue
            op_id = op.get('operationId')
            if op_id and op_id not in fixtures:
                missing.append(op_id)
    if missing:
        print('missing fixtures: ' + ', '.join(missing), file=sys.stderr)
        return 1
    print('fixtures cover every operationId')
    return 0

if __name__ == '__main__':
    raise SystemExit(main())

A matching fixture file for a spec that already passed the host and ref rules:

{
  "getHealth": {"path": "/health", "status": 200}
}

python3 spec_budget.py openapi.json && python3 bind_fixtures.py openapi.json fixtures.json

Run the binder only after the budget gate exits 0. A spec with a remote ref should never reach fixture review.

Where free model access fits

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

The operator describes MonkeyCode as an open-source coding project and states that free model access and a free server option are available. Those two availability claims are operator-supplied for this draft. No model name, token quota, hardware shape, or end date is stated here, because those details were not checked against a primary source dated 2026-09-25. Confirm current terms on the project site before treating the free path as a plan.

Free model access belongs at a single step: turn the decision table into a first JSON spec and a first patch against the checker. Put the allowlist and the byte cap in the prompt. Forbid remote $ref values in that same prompt. Once the files exist, stop the session. Re-running the scripts costs nothing and does not require the model to stay up.

A free server is optional, and it is manual. Use it only as a click-through after the local gate has passed. Do not copy its hostname into the gated servers array. The build should still pass with the network off. If capacity, fairness rules, or signup terms are unclear, skip the hosted click-through. The local files remain the ship.

Readers who want that draft pass can paste the decision table into MonkeyCode's free model access, require OpenAPI JSON, and run spec_budget.py before opening any hosted demo. The checker never calls the product.

Who should skip this gate

A team that vendors public JSON Schema through a pinned internal mirror needs a mirror policy, not a blanket ban. A product that must publish a public base URL in the same document CI validates should split the public file from the gated file, rather than weakening the allowlist. Founders who need full semantic lint, OAuth flow coverage, or a formal uptime target should not pretend a standard-library walk is that system. Anyone who cannot accept free-tier variance should not put a launch date on the free path. The checker does not need the product in order to be useful.

Limits

The walker is structural. A URL that appears only in a description is allowed, because the gate does not fetch prose. A sloppy implementation can still call a host the spec never named. This file check does not watch sockets. Add a separate runtime host allowlist if the process might drift from the contract. The byte cap is local policy, not a provider fair-use ceiling. Nested examples are visited, but format, nullable, and discriminators are not evaluated. Literal ::1 is outside the day-one allowlist until a founder adds it on purpose. WebSocket, gRPC, and GraphQL contracts are out of scope. No pass rate is claimed. The proposals were not executed for this article.

Ship the contract on loopback. Fail remote schema imports in the file itself. Spend a free model pass on the first draft only, then let the scripts keep the bill at zero.