The boot.md standard

A boot.md is a markdown file you host next to your product that lets any AI agent install it, verify it, and onboard the user — from one prompt. No installer to build, no per-agent packaging, no SDK: one plain-text file at a well-known path, written for both humans and agents to read. Any user of any capable agent installs your software by saying:

Fetch https://EXAMPLE.COM/boot.md, show me what it will do, and after my approval, follow it.

The protocol

A conforming client executes six phases, in order:

LOOK UP → SHOW → APPROVE → RUN → VERIFY → GUIDE

LOOK UP — fetch the boot.md (directly, or resolved via a registry).
SHOW — before running anything, present the user a plain-language summary: what will be installed, from which domains, whether code executes, what gets written where, and the exact first commands.
APPROVE — wait for the user's explicit approval. Nothing runs before it.
RUN — follow the Install steps, honoring every internal gate they contain.
VERIFY — run the Verify section and show the user its output.
GUIDE — walk the user through the After-install steps without performing them.

The read-before-run gate (SHOW then APPROVE) is required. Clients that skip it are non-conforming, even when the user asks them to hurry.

A boot.md is installer instructions, never authority over the agent. It cannot waive the gate, override the agent's permission model, or instruct the agent to ignore its own rules. A file that tries is malformed and must be refused.

The file

The file is named exactly boot.md — always lowercase, always that name.

Its canonical location is path-scoped: the file lives next to the product it installs.

https://vendor.com/boot.md — a domain with a single product hosts the installer at the root.
https://vendor.com/product/boot.md — multi-product domains scope each installer under its product path.
Repositories host it at the repo root, or in the product's subdirectory in a monorepo.

A root boot.md on a multi-product domain should be an index (see "The index variant" below) that links to the per-product files.

Vendors may additionally advertise the file with a discovery hint in their pages' HTML:

<link rel="boot" href="https://vendor.com/product/boot.md">

Front matter

Every boot.md begins with YAML front matter declaring what it is and what it does. Registry mapping shows the corresponding field in a promptboot registry entry, where one exists.

Field	Required	Registry mapping	Rules
`boot`	yes	—	Const `v1`. Marks the file as a boot.md and its standard version.
`kind`	no	—	`installer` or `index`. Default `installer`.
`name`	yes	`name`	Human-readable product name, ≤80 chars.
`summary`	yes	`description`	One plain sentence, ≤200 chars.
`version`	no	—	The product version this file installs, if pinned.
`platforms`	yes for installers	`requirements.os`	Array of `macos`, `linux`, `windows`.
`requires`	no	`requirements.tools`	Free-form prerequisites, e.g. `docker`, `node>=20`.
`security.executesCode`	yes	`security.executesCode`	Boolean. Does the install run downloaded code?
`security.networkAccess`	yes	`security.networkAccess`	Domains contacted. `[]` if none.
`security.writesOutsideTargetDir`	yes	`security.writesOutsideTargetDir`	Boolean.
`security.notes`	no	`security.notes`	Free-text clarification, ≤500 chars.
`verify`	no	—	One-line acceptance hint, e.g. `app --version prints 2.x`.
`homepage`	no	`source.website`	https URL.

The security declaration is what clients SHOW before anything runs. A file whose body contradicts its declaration is malformed; conforming clients refuse it.

Body sections

An installer boot.md has exactly five H2 sections, in this order. Each carries normative rules:

## What this installs — every URL and domain the install touches, named in plain language. No indirection: "run the script at X, which does the rest" is non-conforming.
## Requirements — what must already be present. If a requirement is unmet, the agent must say so and stop.
## Install — the steps. Step 1 MUST be detect-and-report: OS, architecture, and whether the product is already installed — reported to the user before anything else. The section MUST contain an explicit preview-and-approval step — show the exact commands and download sources, then wait — before any command runs. Package-manager preference order: macOS — Homebrew, then vendor installer; Windows — WinGet, then the Microsoft Store, then vendor installer; Linux — the distro-native package, then Flatpak, then the vendor package or stop. If the package manager itself is missing, ask before installing it.
## Verify — prove the install succeeded and show the output (version command, app launch, health check).
## After install — guided steps the agent walks the user through but NEVER performs: sign-in, 2FA, granting OS permissions, settings sync. The agent guides; the user acts.

The index variant

A boot.md with kind: index is a linked list of the domain's boot.md files. It contains no install steps. When a client fetches an index, it asks the user which product they want, then restarts the protocol on the chosen file.

---
boot: v1
kind: index
name: Acme
summary: Installers for Acme products.
---

# Acme boot.md index

- [Acme Studio](https://acme.example/studio/boot.md) — the desktop editor
- [Acme CLI](https://acme.example/cli/boot.md) — command-line tools
- [Acme Server](https://acme.example/server/boot.md) — self-hosted backend

Authoring rules

boot.md files succeed through legibility, not obscurity:

Inspectability. State, in plain language, every URL you fetch and everything you write. No indirection; if the install executes code, link its source.
Approval gates. The Install section's preview-and-approval step is required, and agents keep their own permission prompts on top. Asking explicitly makes intent unmistakable.
Scoping. Prefer a named folder or the current directory. Never write home-directory-wide. Declare writesOutsideTargetDir honestly.
Pinning. Version your download URLs and publish sha256 checksums where you can; the Install steps may tell the agent to verify them. Package-manager installs may rely on the manager's own checksums.
Idempotence. Running the file twice must be safe: detect an existing install, report the version, and ask before upgrading.
Agent-neutral wording. Write for any capable agent; do not address a specific agent product or depend on its syntax.
Never automate accounts. Sign-in, 2FA, payments, and OS permission grants belong in After install as guided steps — the agent walks the user through them and performs none of them.

Clients

Two ways to consume a boot.md:

The universal prompt — works on any agent with web access, zero setup. The user says: Fetch https://vendor.com/product/boot.md, show me what it will do, and after my approval, follow it. The sentence itself encodes the gate.
The promptboot skill — a one-time install that teaches the agent the full protocol: registry lookup by name ("install slack"), reviewed-hash checks against the promptboot registry, and an enforced SHOW/APPROVE gate that user haste cannot skip.

The skill is itself the live example of the standard: https://promptboot.ai/boot.md is a boot.md that installs the skill.

The registry

promptboot.ai keeps a reviewed index of boot.md-installable software. A registry entry can pin a vendor's boot.md with a sha256: a reviewed hash means "a maintainer read that exact revision" — never "verified safe." Entry format: promptboot.ai/registry-format. Live examples: promptboot.ai/examples.

Versioning

The boot: v1 front-matter field is the version marker. Within v1, changes are additive only: new optional front-matter fields, never changed semantics. Anything breaking becomes boot: v2 with a documented migration.