Reference

Registry

The registry at edgepython.com stores the packages edge publish sends. edge add and edge lock read it to resolve a name. Its listings and these pages also answer over HTTP.

Publishing

edge publish uploads a .edge packed by edge build. The artifact is the whole request.

• The registry reads the name, the version, the description, the repository, the LICENSE and the doc pages out of the bytes it is about to store. A listing only ever shows what you shipped.
• The artifact is stored exactly as it was packed.
• An author and a date come from the account that publishes. The license comes from the LICENSE file the artifact carries. None of the three is a manifest field.
• A name is first come and permanent.
• A version is never overwritten. Publishing the same one twice is refused with exit code 2.

Signing

EDGE_TOKEN holds a token from the settings. The CLI derives an Ed25519 key from it and signs the digest of the artifact with the current time. The registry keeps only the public key, and the token never leaves your machine.

Package fields

The CLI and the registry check the shape of these edge.json fields with the same rules. The compiler ignores them.

A name is never all, main or eval, which permissions reserve. It is never the name of a system module either.

Quotas

An address is cheap to come by and a provider account is not. The room shows in your settings, and you can ask for more where the figure is shown.

Package docs

When edge.json declares a docs directory, edge build packs every .mdx page under it into the .edge. The site renders those pages on the package listing. A page that breaks a rule below fails the build.

• A page nests two folders deep at most, a section, its groups and their pages.
• Every path segment carries a numeric prefix, like 01-reference/02-cli.mdx.
• A page opens with a closed frontmatter block that holds a title and a description.
• A page has exactly one top-level # heading.
• An output block sits only ever directly after an edge-python block.
• An edge-manifest block sits only ever directly before an edge-python block. It holds one JSON object, the edge.json that example runs under, such as { "permissions": { "main": ["time:wall"] } }.
• An example without an edge-manifest block runs under {}.
• Prose stays markdown and raw HTML is refused. Inline code can still write about a tag such as <script>.
• Hidden files and folders are skipped.

The site holds its own docs to the same rules.

Boxes

A blockquote whose first line is a marker draws a box. A blank line ends the box, and prose may not run on from it.

• A card icon is the name of a Lucide icon from the release the CLI embeds.
• A card or a banner links only to https or to a path on the site.
• A marker opens a box only on the first line of a quote.
• A box other than [!COPY] may not be empty.

> [!TIP]
> Run edge lock after every change to edge.json.

> [!QUESTION] Does a script reach the network?
> Only the hosts its edge.json grants.

> [!CARDS]
> - `play` [Quickstart](/docs/get-started/quickstart) Run a first script.
> - `book-open` [Modules](/docs/reference/modules) What edge.json declares.

> [!BANNER] Ready to share it?
> [Publish a package](/docs/reference/registry#publishing)

> [!COPY] edge add json

HTTP API

Everything the site shows answers as data at the same address under /api. Nothing here needs a token, and nothing here counts against a package.

Search

GET /api/search?q=<term> runs one query over four shelves. It answers with docs, people, services and packages. A hit carries the address it was found at, and its data is that address under /api.

{
  "docs": [
    {
      "title": "Save, persist, restore",
      "where": "Language · Snapshots",
      "href": "/docs/language/snapshots#save-and-restore",
      "snippet": "…a worker keeps its heap between calls…"
    }
  ],
  "people": [], "services": [], "packages": []
}

• A query matches pages that contain all its words, in any order.
• On these pages any form of a word matches, so installation finds install.
• A term shorter than three characters reaches names and headings only.

Read

• ?v= reads an older release of a package. The bare address reads the newest one still live.
• Reading a package never moves its download number. Only edge add counts one.

Ask

POST https://chat.edgepython.com answers a question out of these same pages, in the language it was asked in.

curl -X POST https://chat.edgepython.com \
  -H 'content-type: application/json' \
  -d '{"question": "how do I declare a package?"}'

{
  "text": "Declare every module in edge.json and run edge add <name> [1]",
  "sources": ["https://edgepython.com/docs/reference/modules#edgejson"],
  "session": "pK3f…"
}

• sources holds the page each cited sentence came from, in the order text numbers them.
• A question the documentation does not cover gets a line saying so rather than a guess.
• Send session back with the next question to continue the conversation. A follow-up like and if it is private? keeps what it refers to.
• A session ends once it has gone quiet for a while. An ended id opens a new conversation rather than failing, and the id you get back is the one to keep.
• A 502 is an answer that did not come back. Ask again.