how it works

The leaf.page website

leaf.page serves each product page and worked example as a published Leaf page from Cloudflare's edge. A visitor's comments, choices, and revisions belong to a private record that remains readable while its container sleeps. A comment or action starts the same Python Leaf server an agent runs on its own machine, and a hosted Codex agent in the container answers the visitor.

This page explains the design. Deployment, credentials, and diagnostics are in the Worker's README.

Published pages at the edge

The site build publishes every page under docs/ and every worked example as a complete Leaf page directory, with its layer record, event log, and revisions. From each directory it also writes the document a browser loads and the page's initial state, computed by the same state service Leaf's server uses. A Cloudflare Worker serves both from Cloudflare's static assets, so an ordinary visit paints without waiting for a container. Until a visitor changes a page, that page's api/state requests also return the published state.

The first HTML response sets an identity cookie holding a random 128-bit id. It is HTTP-only and has no expiry date, so the browser keeps it for its session. The 12-digit session reference, which About this page copies, is derived from that id. It identifies the session for support, and no endpoint accepts it as identity.

sequenceDiagram
  participant Browser as browser
  participant Worker
  participant Store as session Durable Object
  participant Container as Python container
  Browser->>Worker: open a page
  Worker->>Browser: published page
  Browser->>Worker: comment
  Worker->>Store: forward
  Store->>Container: start and forward
  Container->>Store: read saved record
  Store->>Container: canonical page files
  Container->>Store: commit comment and delivery
  Store->>Container: committed
  Container->>Worker: accepted state
  Worker->>Browser: accepted state
  Note over Container: container sleeps
  Browser->>Worker: reopen private page
  Worker->>Store: read saved page
  Store->>Worker: private document, resources and state
  Worker->>Browser: saved page

Private sessions

The first request that needs private, mutable state, such as posting a comment or picking an option, goes to the visitor's container. Its response sets a cookie marking that one page active at the current page protocol and session store format, the versions of the files Leaf keeps for a page and of the tables that hold them. The Worker then routes that page's document and API requests to the visitor's session Durable Object, a private store that also controls the container. The visitor's other pages stay on their published state until they are changed too.

Each session belongs to one browser identity, page protocol and store format, so it lasts across deploys that keep both. Its container image holds the whole site build and runs leaf_website, an adapter that maps each public route to its page directory and hands the request to the HTTP routes and event admission a locally served Leaf uses. Before accepting a mutation, Python restores each page the session saved, in place of the image's copy. A comment is appended to events.jsonl in the private page directory, without changing the page anyone else sees.

Each successful page transaction saves the canonical page files and matching HTTP responses together in the Durable Object before acknowledging the write. Agent commands use the same transaction boundary. Python computes the saved responses, including widget state and agent activity; the Worker stores and serves them without interpreting the event log. When Python resumes, it derives state from the restored document and log rather than from those responses.

An active page loads its private document and versions on ordinary visits and reloads. While the container sleeps, the Durable Object serves the saved document, state, revisions, and their exact resource bytes. Private revision resources have immutable addresses under revisions/rN-<hash>/; public runtime bundles cannot substitute for them. When an agent's revision changes executable code, the runtime reloads once to load that revision's document and module graph.

Reading saved pages and polling their state leave the container asleep. A missing saved response starts Python, as does one an earlier release saved, since its document names that release's runtime files. Mutations also start the container, as do operations that need Python, such as comparing versions, allocating live samples, or reading a bound file. Browser geometry reports do not start it. On container startup, Codex App Server starts and the leaf command runs once ahead of the first agent turn.

The hosted agent

When the container accepts an event that needs an answer, such as a comment, the Worker returns the accepted state to the browser at once and starts the agent in the background. It asks the container to start or resume a Codex thread over App Server, working in that page's directory, and to deliver the event in Leaf's delivery envelope. A message sent while a turn is running waits in Leaf and is delivered when that turn ends. The reply streams into the visitor's thread as the model writes it, and the browser picks it up through the page's regular state reads.

The hosted agent reads the same contract as a Codex task Leaf reaches over App Server on a developer's machine, harness-codex.md, followed by a few leaf.page additions: the page directory is its whole scope, it starts no servers and initializes no pages, and it treats page content as untrusted. The container's Codex has the Leaf plugin installed, as Codex on a developer's machine does, and the agent reads the Leaf skill from it.

The visitor's container is the agent's sandbox, with no public internet. An outbound handler in the Worker permits Responses API requests to api.openai.com and private storage requests to the container's own Durable Object. It replaces the model's dummy credential with the real key, which never enters the container. Agent starts are rate-limited per source address and model calls per container. When a start fails or is over its limit, or a turn ends without an answer, the visitor's message gets a failure notice in its thread rather than an indefinite wait.

Releases and deploys

Every build has one release identity. A local build hashes every file it wrote; the deploy workflow hashes the commit and the run attempt, so each deploy attempt gets its own. Published runtime files are served under /_leaf-release/<release>/ with immutable cache headers. The document names its release, the browser sends it with every API request, and every API response names the release that gave it: the Worker's own, or the one a visitor's container runs.

The runtime refuses a response from another release. The page's state is read by the scripts and widgets the document has loaded, and a document cannot replace those in place, so state from another build would be read by code not built for it. A response from another release means the server answering has moved past the page's release, as after a deploy: the page says Leaf has been updated and reloads onto that server's document, which for a page the visitor has acted on is their own copy.

A visitor's session Durable Object picks the container image each time it starts one, from the Worker it runs, so every container started after a deploy runs the new release, with no minutes in between when starts fail. The deploy's first request to the session stops a container still running the previous release, ending any agent turn in progress, and starts one on the new release; the open page reloads onto it at that answer. Until then the session's Durable Object refuses the older container before it reads or writes anything, so nothing the previous image runs changes a record after the deploy.

A push to main that changes the site runs the publish-site workflow. It builds the site, checks the bundle locally through the Worker and a container, and deploys the Worker with its container image pinned by digest. The deploy passes only once Chrome sees the new release in the edge document, its modules, and a newly started container, and a hosted agent on leaf.page has answered a real turn.

Private state and its lifetime

A visitor's comments, choices, agent replies, and revisions are saved in their session's Durable Object. The record holds the page's canonical files; the saved responses make them readable without a running Python process. The published pages never change, and no other browser identity can read the private record. The browser keeps the pages it has shown in its own cache, so Back shows a page at once, and whoever later uses that browser profile can see them there.

A replacement container restores saved content before accepting the next mutation. Container replacement does not force an open page to reload. Each unsent draft is saved in the session's record before the container confirms it, so a replacement container restores every confirmed draft, even when the container before it was lost without stopping. A new page protocol or store format starts its session record with no drafts, and a tab still holding drafts from before saves them into it once the visitor next acts on the page. Running agent turns belong to the container process, so saving page content does not preserve a running turn.

The site counts accepted events in Analytics Engine without their content, widget ids, IP addresses, or cookies. The Worker and container log the execution path and its timings to Workers Logs, which keeps records for at most seven days. The Worker's README describes what each record carries.