The fastest way to understand the Hypermedia protocol is to read a document three ways and then publish one. You do not need to run a daemon or a server. Every request goes to https://hyper.media, the public gateway, and the key you create stays on your machine.
Goal. In fifteen minutes you will fetch a document with curl, with the SDK and with the Seed CLI. Then you create an account key, publish a home document and a page under it, and see them on the web.
Prerequisites. curl, and Node.js 18 or newer. The CLI's key storage uses the OS keyring and needs macOS or Linux. The CLI's key store does not support Windows yet, so on Windows use a key file, described in keys.
1. Read a document with curl
Every document has an hm:// id: the account that owns it, then a path. This one is the self-hosting guide on the Seed team's site.
curl 'https://hyper.media/api/Resource?id=hm://z6Mko5npVz4Bx9Rf4vkRUf2swvb568SDbhLwStaha3HzgrLS/resources/self-host-seed'{"json":{"type":"document","document":{"content":[{"children":[],"block":{"type":"Paragraph","id":"OtLkse-T",…,"text":"If you want to publish on your own domain without relying on our service, …"}},…],"version":"bafy2bzacedia6…","authors":["z6MkfnCSnmst…","z6MkgisVMELv…",…],"metadata":{"name":"Self-Host a Seed Website","cover":"ipfs://bafkreie6…"},"genesis":"bafy2bzacedvbz…",…},"id":{"id":"hm://z6Mko5npVz4Bx9Rf4vkRUf2swvb568SDbhLwStaha3HzgrLS/resources/self-host-seed","uid":"z6Mko5npVz4Bx9Rf4vkRUf2swvb568SDbhLwStaha3HzgrLS","path":["resources","self-host-seed"],…,"latest":true}}}The body is wrapped in {"json": …}. The document is a tree of blocks with metadata, a version (the ids of the changes it is made of) and the accounts that ever changed it. If you only want to read, the same document is one URL away as markdown:
curl 'https://seed.hyper.media/resources/self-host-seed.md'If you have a web link and need the hm:// id, the site tells you the id in response headers:
curl -X OPTIONS -I 'https://seed.hyper.media/resources/self-host-seed' | grep -i x-hypermedia-idx-hypermedia-id: hm%3A%2F%2Fz6Mko5npVz4Bx9Rf4vkRUf2swvb568SDbhLwStaha3HzgrLS%2Fresources%2Fself-host-seedThe full request surface is on the Seed API page.
2. Read it with the SDK
@seed-hypermedia/client is the TypeScript SDK. It knows every request key, encodes inputs, unwraps responses and validates the result.
mkdir hm-hello && cd hm-hello && npm init -y >/dev/null
npm install @seed-hypermedia/client zod@^3.20// read.mjs
import {createSeedClient, unpackHmId} from '@seed-hypermedia/client'
const client = createSeedClient('https://hyper.media')
const id = unpackHmId('hm://z6Mko5npVz4Bx9Rf4vkRUf2swvb568SDbhLwStaha3HzgrLS/resources/self-host-seed')
const resource = await client.request('Resource', id)
if (resource.type === 'document') {
console.log(resource.document.metadata.name)
console.log(resource.document.content[0].block.text)
}node read.mjsSelf-Host a Seed Website
If you want to publish on your own domain without relying on our service, …client.request is typed. The request key picks the input and output types, and resource.type narrows the union. Search works the same way: client.request('Search', {query: 'hypermedia', pageSize: 5}). Zod 3 is a peer dependency. Zod 4 does not work.
3. Read it with the CLI
The Seed CLI wraps the same API for the terminal and for scripts. Agent skills use it too.
npm install -g @seed-hypermedia/cli
seed-cli document get hm://z6Mko5npVz4Bx9Rf4vkRUf2swvb568SDbhLwStaha3HzgrLS/resources/self-host-seed---
name: Self-Host a Seed Website
cover: ipfs://bafkreie6wls4wzt26vl3smvcc5smulmbostaokyftwmig2ojfpkhbmbee4
---
If you want to publish on your own domain without relying on our service, you are welcome to self-host your site. … <!-- id:OtLkse-T -->
This guide is a bit technical, but it will allow you to publish on the web with complete freedom from any single company. <!-- id:fjRkSmjy -->The CLI prints documents as markdown with frontmatter and a trailing <!-- id:… --> comment per block. This dialect round-trips, so you can publish an edited file back. --json gives the structured form. You can paste a web URL instead of an hm:// id, and seed-cli search "self-host" finds documents across the network. The CLI reference lists every command.
4. Create a key
An account is a key. The CLI generates one from a mnemonic and stores it in your OS keyring. The mnemonic is the only backup.
seed-cli key generate --name main --show-mnemonic⚠ SAVE THIS MNEMONIC SECURELY - it cannot be recovered!
<twelve words>
✓ Key "main" created
ℹ Account ID: z6Mk…The account id is a principal: z6Mk followed by the base58 encoding of an Ed25519 public key. It is your account id on the network and the uid in every hm:// URL of your space. seed-cli key list shows it again. To derive the id from a phrase without storing it, run seed-cli key derive "<words>". The standard test phrase abandon … about derives z6MkqqiSjqcT9NasDUXiymyB8kpgz6h3CNQaghGAoXsaYJ2f.
5. Publish
A space begins with its home document. Write a markdown file and publish it at the root path.
cat > home.md <<'EOF'
---
name: My Space
summary: A first Hypermedia space, published from the command line.
---
Hello from the Hypermedia network. This document is signed by my key and stored as content-addressed blobs.
EOF
seed-cli document create -f home.md --path /✓ Document published: https://hyper.media/hm/z6Mk…Now a page under it:
cat > hello.md <<'EOF'
---
name: Hello
---
A second document, one level below the home document.
EOF
seed-cli document create -f hello.md --path hello✓ Document published: https://hyper.media/hm/z6Mk…/helloOpen the printed URL. The gateway renders your space. seed-cli document get hm://z6Mk…/hello reads it back, and seed-cli document update hm://z6Mk…/hello -f hello.md publishes an edit as a new change on top of the existing history. --dry-run shows what would be published without sending it.
What happened
Each document create did three things on your machine. It turned the markdown into a Change blob: a signed, content-addressed record of the operations that build the document. For a new document that first change is also its genesis, the id that names the document's whole history. It then signed a Ref, a small blob saying "in my space, at this path, the document is at this version", and sent both blobs to hyper.media with a single PublishBlobs request. When a new document is two or more levels deep and its parent exists, the CLI also adds a link card to the parent. hello sits directly under the root, so the home document does not change. The gateway's daemon verified the signatures, indexed the blobs, and will hand them to any peer that asks for your space.
Next
Publish a whole folder of markdown and keep it in sync with git: publish a folder.
Build the blobs yourself in TypeScript, with createDocumentBlobs, createComment and createCapability: SDK.
Let an agent read and write your space with a delegated key: using Seed from your own agent.
Sign in a browser visitor to your own app with their Seed account: sign in.
Serve your space on your own domain: self-hosting.
Understand what you just used, from keys to sync: the protocol.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime