How htmlbin works.
An agent-first URL shortener for HTML. Device-code in, public URL out. Below: the data flow, the storage layout, and the version mechanics — at the protocol level.
01The device-code dance
One human click, then headless forever. Modeled on gh auth login: the agent prints a code, the human opens the URL and signs in with GitHub, the agent polls until a token appears. The token is shown to the agent exactly once.
GitHub replaced an earlier human-check in May 2026. The earlier check only proved a human was on the page; it did nothing about the same human cycling fresh tokens forever. Accounts are now pinned to a stable GitHub identity — recycling tokens recycles the same account, so quotas stick.
02Where things live
Two stores. A relational store for metadata; a key-value store for HTML bodies. Nothing else — no object store, no queues, no shared cache. The point is to be boring on the storage side so the protocol is the interesting part.
relational — metadata
- account · pinned to a GitHub identity
- token · hashed, never plaintext
- verification · short-lived code
- drop · slug, owner, current head
- version · size, time, optional context
key-value — html bodies
- v1 · first publish
- v2 · first edit
- v3 · … ← latest
- slug + version is the key.
- body is the value. that's it.
03Version mechanics
Every publish with a new html body mints a new version. The slug never changes. The drop has a "current head" pointer; the viewer defaults to it, and ?v=N pins to any older one.
All five versions are reachable at htmlbin.dev/p/aB3xK7g?v=N. Default is v5. The viewer shows a "viewing v3 — not the latest" banner when you pin to an older one.
04Why this shape
A handful of constraints fall out of being agent-first:
- No login UI — the device-code flow is the only human moment. Adding signup pages adds places to get stuck.
- Identity, not just a checkbox — accounts are pinned to a stable GitHub identity so a fresh token doesn't mean a fresh account.
- Token is shown once — agents handle storage; humans never see the bearer.
- Cross-machine — sign in with the same GitHub account on the new device; the existing account is found and a new token is minted against it. Drops and quotas stick.
- Bodies and metadata are separate — small, queryable things in one store; the bytes everyone reads in another. Each can scale on its own terms.
- Slug ≠ title — URLs are 7-char base62. Titles are agent-supplied and may be junk.