Seed is one public repository, github.com/seed-hypermedia/seed. This page is for people who want to change anything in it. Read it first: it gets the code running on your machine.
The repository holds the Go daemon, the TypeScript apps and libraries, the app environment that runs Seed Agents, the vault, the deployment tools, and the markdown for these docs (see Editing these docs).
This page covers four things:
The layout of the repository.
The development stack, which one command starts.
The checks to run for each area before a pull request.
The rules for changes that are hard to undo: storage migrations and protocol changes.
Working on Seed lists the other guides for contributors.
The repository keeps instructions for coding agents in AGENTS.md at the root and in the folders listed below. They are written for people too. Where this page and an AGENTS.md file differ, the AGENTS.md file is right.
The repository
Path | What lives there | Toolchain |
|---|---|---|
| the Seed daemon: storage and indexing ( | Go, built with Please |
| protobuf definitions for every daemon service; generated Go and TypeScript are checked in | Please, |
| the Seed app (Electron) | pnpm |
| the Seed web app that serves sites, the Seed API and the site services (Remix) | pnpm |
|
| pnpm workspace, runs under Bun |
| the email notification service | pnpm |
| pnpm | |
| the React Native app, outside the pnpm workspace | npm |
| the landing site, email templates, performance tooling | pnpm |
|
| pnpm |
| shared models and hooks ( | pnpm |
| the app environment, the server that runs Seed Agents; see Development | its own Bun workspace |
| its own Bun workspace | |
| this site: concept pages, the Hypermedia Schemas library, the references and guides; see Editing these docs | markdown, |
| the self-hosted node deployment script ( | pinned Bun |
| cross-app integration tests | pnpm, Vitest, Playwright |
| internal design notes and runbooks; not published | markdown |
apps/ and vault/ copy the frontend packages they use through file: dependencies. So a change to frontend/packages/* reaches them only after bun install. Their development servers do this for you. The map pages under The Seed software, such as Daemon, Desktop and Web, explain how the programs talk to each other.
Setting up
mise.toml fixes the version of every tool, and direnv turns them on in your shell.
Clone the repository and allow the environment, with the commands below.
The first direnv allow takes a few minutes. It installs the tools, sets up the llama-go submodule, downloads the embedding model that the daemon uses for search, and builds the llama.cpp libraries.
git clone https://github.com/seed-hypermedia/seed
cd seed
direnv allow
pnpm installInstall Docker too if you want the full stack. The web search backends that agents use run as containers.
./dev only runs in a shell where direnv is active. From a script or a coding agent, run commands as direnv exec . <command>.
Running things
./dev with no arguments lists every command. These are the ones you will use:
Command | What it does |
|---|---|
| the whole stack on mainnet in one mprocs window, one pane per process (see |
| the same stack on the dev testnet (see |
| build the daemon, then run the desktop app on the dev testnet; the app starts its own daemon |
| the same, on mainnet |
| build and run |
| production builds |
| the desktop test suite |
| build |
| edit a markdown folder, |
| check generated code and regenerate what is stale |
| format the whole workspace, then check formatting the way CI does |
./dev up starts these panes:
Pane | Process | Address |
|---|---|---|
| SearXNG and crawl4ai containers for agent web search | :8899, :11235 |
| the Seed Agents server with hot reload | :3051 |
| the web app, talking to the desktop app's daemon | :3000 |
| the Hypermedia Explorer | :5173 |
| the notification server | :3060 |
| the vault | :3030 |
| the Electron app on mainnet with its daemon | daemon HTTP :58001 |
| the hosting service; it runs only when a SeedHost checkout sits beside this repository | :5555 |
| the round trip between |
In mprocs, r restarts the selected process, s stops it, x starts it and q quits everything. Quitting also runs docker compose down for the search containers. The development daemon and the desktop app use ports 58000 to 58004. The full port table is on The Seed software.
Scripts in the root package.json start one app each: pnpm web, pnpm desktop, pnpm notify, pnpm explore and pnpm mobile. pnpm web:standalone runs a web app with its own daemon.
Checks before a pull request
Run the checks for every area you changed. CI runs the same ones. One file with wrong formatting, anywhere, fails the Lint job.
Area | Commands |
|---|---|
Whole TypeScript workspace |
|
Formatting, everywhere |
|
Web, shared, desktop unit tests |
|
SDK, UI, editor, notify, explore |
|
| |
Desktop end to end |
|
Integration |
|
Mobile |
|
App environment |
|
Vault |
|
Dependencies |
|
Go |
|
Docs |
|
Three notes on these checks:
In apps/ and vault/, bun check runs the type checker and fixes the formatting. Commit whatever it changes.
The Go tests need the submodule and the model that direnv allow fetched. CI runs them with go test -tags cpu --count 1 ./backend/....
For a bug fix in the backend, first add a test that fails, when you can. Use testify/require in Go tests.
To run CI on your machine before you push, use agent-ci. Local CI with agent-ci has the setup and the command for each area.
Changes with special rules
Storage schema and migrations
The daemon's SQLite schema is in backend/storage/schema.sql, which is the source of truth. The migrations are in backend/storage/storage_migrations.go. Read the note at the top of that file before you add one. These are the rules it sets:
The version of a migration is a timestamp from date +%Y-%m-%d.%H%M%S. The list is kept with the newest first.
The run function of a migration runs in an immediate write transaction. Write it so that running it twice does no harm, as far as you can.
A migration runs only when its version is higher than the version of the data directory. So never run a feature branch that has a migration against a data directory you care about. Back the directory up first. If you switch back to main afterwards, the daemon fails on the unknown version.
After you change the schema or the migrations, run ./dev gen //backend/....
Avoid a migration that forces a full reindex or computes the embeddings again, unless you must. Servers without a GPU take a long time to do that. Prefer a new column and a background task that fills it in small steps.
If you are not sure, ask the backend team before you add a migration. Tag the maintainers of the Go daemon on pull requests that change backend/.
Protobuf and generated code
Edit the .proto files under proto/, then run ./dev gen //proto/... from the root. Do not run buf or protoc yourself, and do not format the generated code. A proto change reaches both Go and TypeScript callers, so run the backend checks and the frontend checks above. gRPC describes the services for people who call them.
Protocol changes
A protocol change is a change to something that every implementation must agree on:
The structure or the meaning of permanent data: blobs, changes, the graph of changes that makes a document, and the rules that merge edits.
The sync protocol.
The capability model.
The identity system.
Any format that another implementation must read on disk or over the network.
A feature that you can build in an application alone is not a protocol change. The team's advice is to build it that way first.
This is the team's process for a protocol change:
Write a proposal note that describes the problem and the change.
Write down the arguments for and against it in the open. Include the options you rejected.
Decide by working through the technical objections. A vote does not decide.
Update the protocol documentation on this site.
The process is slow on purpose, because published blobs are permanent. Every node that holds old data must still be able to read it.
Deployment tooling
ops/ is built with the exact Bun version named in ops/package.json. CI fails if ops/dist/deploy.js does not match the source. When you change the deploy script, build it again with that version, as bunx --bun bun@<version> build ….
Releasing and publishing
Maintainers make releases with the steps in Releasing. GitHub Actions publishes the npm packages, as Package publishing explains. Sentry covers error reporting.
This site is the hypermedia/ folder. Editing these docs has its rules, its checks and when an edit is published.
Reporting security issues
Report a security issue by email to security@hyper.media. This repository is public. So do not open a public issue or pull request about a vulnerability that is not fixed.
The repository's security-audit skill describes how audits are done, and its audit log lists what earlier audits covered.
See also
The Seed software, a map of every program in the repository.
Getting started, for using Seed without changing it.
Self-hosting, for running a site.
Working on Seed, the list of contributor guides.
Development, for the app environment in apps/.
Editing these docs and Publish a folder, for how these docs round-trip.
Daemon gRPC, for the services the protobuf files define.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime