Use this glossary when moving between Energon’s user, operator, and contributor guides. Precise terms matter because “owner,” “share password,” “write password,” and “token expiry” name different controls; treating them as synonyms can expose content or block the wrong writer. The definitions cover the stable product model. A live Energon’s /v1/help response remains authoritative for configured names, limits, defaults, and lifetimes.

Glossary

Relationship map

Published content

Site
A named collection of public files under one stable public URL. Identity is a generated 6-character id, the same shape as a loose-file id. The slug is a friendly label and is not unique. The public URL is /{handle}/s/{id}/{slug}/. The site exists in the D1 catalog even before it has paths.

Site file
One relative path inside a site version. D1 stores its catalog metadata and R2 stores its bytes under a key that is never overwritten.

Site version
An immutable snapshot of a site’s complete file set. The site points at one active version; publication moves that pointer while the URL stays the same. Each request selects the active version when it starts, and the X-Energon-Site-Version response header names it. Older versions are retained only for in-flight reads and cleanup, not as browsable history.

Content generation
A content_generation counter on a site or loose file that increases each time its published bytes are replaced. Password, expiry, and write-policy changes leave it alone. A conditional write names it as expected_version: a site deployment’s commit fails with 409 deployment_conflict if it changed, and a loose-file PUT or file upload grant fails with 409 file_conflict. It is a counter, not a digest, so restoring earlier bytes still counts as a new generation.

Site deployment
An upload session that stages a complete replacement file set for one site, prepares it, and publishes it in one explicit commit. Sessions last one hour; committed receipts last seven days. A deployment replaces; a ZIP import merges.

Whole-site grant
An upload grant with target site_deployment, bound to one existing deployment session. It lets a machine without a token upload the session’s declared inputs, prepare, and commit, but not change the intent or site settings.

Read lease
A short D1 record that keeps the site version a request selected from being cleaned up while the response is still being served.

Loose file
One standalone published object identified by a generated id. Its readable filename may change during PUT, but the id remains its identity.

Hub
The human-facing interface on the hub origin. In production, Cloudflare Access protects its setup, token, and account pages.

Hub origin (PUBLIC_ORIGIN)
The Worker hostname that serves the human hub and the /v1 API. Cloudflare Access authenticates human hub requests; agent keys authenticate /v1 requests.

Content origin (CONTENT_ORIGIN)
The distinct production hostname that serves published site and loose-file bytes. It does not serve hub account routes and must remain outside Cloudflare Access.

Public content URL (url)
The returned human-facing address on the content origin. It is open by default and may have a share-password gate. When the object’s link access is private, it refuses every request with 403 link_private. When a write password is set, the same URL accepts guest PUT (and site-path DELETE) with X-Energon-Write-Password.

Authenticated API URL (api_url)
The returned raw-byte address under /v1 on the hub origin. It requires a valid agent key and does not apply the public share-password or write-password gates.

The two URL shapes look like this, but clients should keep the returned fields instead of constructing them:

CONTENT_ORIGIN/{handle}/s/{id}/{slug}/
CONTENT_ORIGIN/{handle}/f/{id}/{filename}
PUBLIC_ORIGIN/v1/sites/{id}
PUBLIC_ORIGIN/v1/files/{id}

Identity and access

Operator
The individual or organization that controls an Energon’s Cloudflare account, deployment, D1 and R2 resources, Access policy, hostnames, and rendered agent skill.

This Energon
The deployed product: one Worker, D1, R2, Access app, and rendered skill. Speak of “this Energon” or “your Energon.” The user-facing CTA is Want to deploy your own Energon? GET /v1/help describes this Energon: origins, skill and marketplace coordinates, token environment variable, token prefix, retention, token policy, and limits.

Well-known skill
This Energon’s rendered publish skill, served publicly from its content origin under /.well-known/agent-skills/ so installers and tool gateways can load it by URL without access to the deployment repository. It names the same origin, token environment variable, and token prefix as GET /v1/help, includes the energon_publish.py upload helper, and holds no credentials. /v1/help agent_skills_url is null when the operator turns it off with AGENT_SKILLS_DISCOVERY. See Use Energon through a tool gateway.

Gateway catalog
The subset of this Energon’s OpenAPI contract that a tool gateway should import, served at /v1/openapi-gateway.json from v1.14.0. It keeps grant, deployment, metadata, read, and cleanup operations and leaves out byte uploads, zip exports, content-origin grant redemption, self-revoke, the connection flow, and admin operations, so an agent searching the gateway’s tools finds only the grant route for local files. /v1/help gateway_openapi names it. See Use Energon through a tool gateway.

Org
Everyone who can create an agent key on this Energon (Cloudflare Access, with an optional email-domain lock). Not a database entity. Write policy org means any of those keys may write the object. Hub copy says “Anyone in the org.”

Host
Locative only: the place (this origin, versus someone not on this host). Not the name of the product. Do not say “host identity,” “deploy your own host,” or “deploy your own instance.”

Agent key
A credential issued after a human approves an agent connection or creates one by hand at /keys. The API, environment variable, and error codes call it a token (ENERGON_TOKEN, token_expired). It lets an agent use /v1 as the owning account. Clients send it with Authorization: Bearer; the full secret is delivered or shown once, while Energon stores a hash and masked hint. An expired key cannot be renewed. GET /v1/whoami reports scope (account or admin) and admin. DELETE /v1/whoami revokes the calling key only.

Admin
An account whose email is on ADMIN_EMAILS. Admins create admin keys at /keys. Connect never grants that scope. Removing the email from the list strips admin from every key they already created.

Admin key
An agent key created with admin scope. It still acts as the owning account for ordinary /v1 calls. Admin routes also require the owner to remain on ADMIN_EMAILS. Lifetime is at most 7 days and cannot be never. The stored hint inserts admin after the token prefix.

Key prefix
The marker at the start of an agent key that this Energon accepts. Key creation, authentication, masked display, and agent documentation must agree on it.

Link access (link_access)
A per-object setting, from v1.15.0, that decides whether the public content URL opens at all. public, the default, serves anyone with the link, gated only by an optional share password. private refuses every public-URL request, including guest writes, with 403 link_private, and limits the object to its creating account: only that account’s agent keys can read or write it through /v1, and every other account gets 404. A private object has no share password or write password, and its write policy is always owner. Only the creator can change it, and copies do not inherit it. Hub copy says Anyone with the link and Only you and your agents. See Keep work private to your account.

Share password
An optional gate on one public content URL. Browsers use the gate form and cookie. Agents send X-Energon-Password. It is not a named-user ACL, does not restrict /v1 reads by valid agent keys, never authorizes PUT or DELETE, and cannot be set on a private object. The Hub keeps the phrase so the creator can copy it again. Last writers cannot recover or change the owner’s phrase. /v1 GET returns only password_protected.

Write password
An optional per-object shared secret that lets someone outside the host replace bytes at the public content URL without an agent key, Access, or /connect. Agents send X-Energon-Write-Password on PUT, and on DELETE of a site path. The write header also unlocks GET. The HTML gate form accepts the write password for reading when a share password is also set. The cookie never authorizes PUT or DELETE. A write password is not an account and is not recorded as Last writer; the Hub shows “Updated via shared write.” Only the creator may set or clear it. Duplicate does not copy it. /v1 GET returns only write_password_protected.

A loose-file write password only replaces that file, including an empty body. A site write password can add, replace, or delete paths under that site, including index.html, and cannot delete the site. Guest DELETE of a loose file or of the whole site is out of scope so the minted public address still resolves.

Upload grant
A short-lived, single-use credential a token holder mints with POST /v1/grants so a machine without a token can upload one file: a new loose file, a replacement for an existing one, or one path in a site. The machine sends raw bytes to the grant’s upload URL on the content origin with Authorization: Bearer and the grant secret. The upload acts as the minting account: it must pass that account’s write policy, and the account becomes the writer. A grant is not an account and cannot be used as an agent key. A successful upload publishes at once and uses the grant up. Its lifetime (5m to 1h) is its own credential policy, separate from token expiry and content TTL, and never outlasts the minting token; revoking or expiring that token ends the grant. See Let a machine upload without a token.

Write policy (write_policy)
The per-object mutation rule for authenticated /v1 writers. owner permits only the creating account to PUT, PATCH, or DELETE; org permits any valid agent key on the host. Neither value restricts reads; link access does. A private object is always owner. A valid write-password PUT still succeeds when the policy is owner, because guest write is a separate door.

Handle
The public namespace derived from a human identity and snapshotted on content. Use returned URLs rather than guessing it from an email address.

Lifecycle and coordination

Last read (last_read_at)
When this Energon last served a site’s or loose file’s bytes over the public URL or /v1. It is a floor, not a view count. Stamps are throttled to about one write per hour. Loose-file reads answered from the edge cache never reach the Worker, and that cache lasts at most one day, so a loose file’s stamp lags real public reads by at most about a day plus the throttle. From v1.10.0, every site read reaches the Worker, so a site’s stamp lags only by the throttle. An absent value means no recorded read, never unread. Hub catalog cells say None.

Platform quota

The running storage ledger every publish reserves against, so concurrent writes cannot jointly exceed the platform cap. Catalog sizes are the source of truth. An interrupted release can leave the ledger too high and refuse valid publishes. Recomputing quota repairs that total without deleting content; orphan R2 bytes with no catalog row are not counted.

Content TTL
The lifetime of a site or loose file. Creation or a PATCH with ttl sets expiry; PUT changes bytes without extending it. Expired reads return 410 Gone even before cleanup finishes.

Token expiry
The independent lifetime chosen when a human creates an agent key. Expiry returns terminal 401 token_expired; it does not delete content.

Write claim
A temporary leased D1 marker granting one loose-file mutation exclusive permission to coordinate its R2 and catalog change. An abandoned claim becomes reclaimable after it is stale.

Purge claim
A temporary D1 marker granting expiry cleanup exclusive permission to remove one expired loose file from R2 and the catalog without racing revival or replacement. From v1.10.0, expired sites are marked removed and reclaimed through version cleanup instead.

Schema bootstrap
Runtime creation of absent tables plus supported additive upgrades. It helps older Energons start but does not replace migration history.

Legacy schema upgrade
The additive bootstrap path from a supported older database shape without rebuilding its persisted identity relationships.

Index phase
The final bootstrap stage, after all required tables and columns exist.

For the controls in context, read Security model and Sharing, access, and expiry. Architecture places claims and schema bootstrap in the system, while HTTP API is the route and field reference.