What a publish primitive is
One call in, one URL out. No project to create, no build to run, no DNS to point, no
settings page to visit first. The verb is the whole product: hand it a document, get back an
address you can paste to somebody. publish_html is that verb here, and
POST /sites is the same verb without an agent in the loop.
The granularity mismatch
Project-shaped hosting assumes the unit of work outlives the setup. Connect a repository, configure a build, wire a domain — an hour of work that pays back over a year of deploys. Agent output inverts the ratio. The artifact is finished the moment it is written, has one intended reader, and is frequently irrelevant by the end of the week. Setup cost larger than the artifact's whole lifespan is not a small inefficiency; it is the reason the artifact never gets a URL at all and ends up pasted into a chat window as a wall of markup.
Three things agents do that break the old shape
- Volume. One session emits a spec, a status report, a diff viewer and two throwaway dashboards. None of them is a project. All of them want an address.
- Revision. The same artifact gets rewritten eight times in an afternoon. If every revision mints a new URL, the link you sent at revision two is stale before it is opened.
- Real data. Agent output is assembled from whatever was in context, and context is full of query results, customer rows and occasionally the token that fetched them. Public-by-default stops being a defensible baseline.
What the primitive has to guarantee
Four properties, and the fourth is the one usually missing:
| Property | What it means here |
|---|---|
| One call | publish_html or one POST. No prior state to create. |
| Replace in place | update_site swaps the bytes behind the same token. The bookmark survives. |
| Private first | A 22-character random token, noindex, no-referrer, and a
strict CSP without asking. |
| Disposable | Links expire on a default, and the purge deletes the row and the stored object rather than hiding them. |
Why it is hard to bolt onto a project host
Not because the code is hard — because the product keeps pulling the artifact back into project shape. Once folders, environments and branch previews exist, everything acquires them. A primitive stays useful precisely by refusing that gravity: twelve tools is enough, and the thirteenth is usually a workflow somebody wanted instead of a verb.
What changes when the verb is right
The agent stops switching modes. Publishing becomes the same kind of act as writing a
file, so it happens inside the loop instead of after it. The URL becomes a handle the agent
can carry into its next turn — it can re-read the page at /raw/:token, replace it,
gate it, or read back what the reader did with it. The human bookmarks once.
Where the primitive is the wrong answer
Anything with a lifecycle. A customer-facing product, something that must be archived for years, anything wanting branch previews or A/B tests or a build step that pulls dependencies. Those want a deploy platform, and this deployment does not try to be one — there is no build, no server-side runtime for your code, and no version history: replace-in-place overwrites the same object, with nothing to roll back to.
Why this repository exists
This deployment is the primitive with the metering removed. Same twelve tools, same access-control surface, running on one Cloudflare account you own, from https://github.com/yao00oo/opentree. If the bet — that publishing becomes as load-bearing for agents as file-writing was for editors — turns out to be right, the verb should not be something you rent per call.
Is a publish primitive just a paste bin?
In spirit, yes, and that is a compliment. The differences that matter for agents are replace-in-place under a stable URL, access control per link, and a machine-readable surface — twelve MCP tools and a REST API rather than an HTML form.
Why not just use a static host with an API?
You can, and for a real project you should. The friction is not the API call, it is everything the API call assumes already exists: a project, a build configuration, a deployment record. Those are assets for a product and overhead for an artifact.
Does the URL really stay the same across revisions?
Yes. update_site and PUT /sites/:idOrSlug write over the same stored object
under the same token. The trade is that there is no history — the previous revision is gone,
not archived.
Can a human use it without an agent?
The homepage has a paste box that publishes anonymously over POST /v1/publish, and
curl -F file=@index.html works with an API key. The agent path is the design centre,
not a requirement.