An app is a document that groups small programs into one thing people can share and run. For example, a reading-list app can hold a page that shows the saved articles, a tool that fetches an article's title from the web, and a trigger that calls that tool every hour.
The app's metadata declares type: hm://hyper.media/app. An app has three kinds of child document:
This page says what an app is made of, what runs where, and where its data lives. To make one, follow building an app.
What an app is made of
Every child lives directly under the app, one path segment down. For example, /apps/weather/forecast is a child of /apps/weather. The app lists each child with a card embed in its content.
The embeds are the source of truth:
They say which children belong to the app, and in what order.
A document under the app that the app does not list is not part of it.
Any top-level embed of a direct child counts. Seed writes them as cards.
Sharing the app shares the list.
The app's own metadata holds:
Attribute | Value |
|---|---|
|
|
| the app's name and description |
| the hm:// URL of one of its own pages, shown when the app opens |
| settings every page and tool of the app can read, such as the addresses of its collections |
| the schemas of the public config and of the private config |
| the app environment that runs the app. The New app dialog sets it to the server you pick. Without it, the app uses the one that the site of the app's space advertises |
The private config itself is not in the document. Only the server that runs the app holds it.
Running an app
A writer of the app's space runs the app on an app environment and gives it the private config. The server keeps that config encrypted. It checks the config against privateConfigSchema before each tool call.
An app runs only on the server it names. A server that the app does not name refuses to run it or its tools.
The server reads the app and its tools from its own node. That node may not hold a document yet, for example one published from a desktop or through another site. The server then looks for it on the network first. This can take up to 25 seconds.
While the app runs, anyone can call its tools, and its triggers fire. When the app stops, both stop.
What runs where
A tool takes input and returns output. It runs in a sandbox on the app's server, with internet access. It holds no signing key and cannot reach the Seed node of the server that runs it. So it neither publishes documents nor reads them: whoever calls it passes the records it needs. It has no language model either. Judgment work, such as summarizing or classifying, needs a model API key in the app's private config, or belongs to an agent. See tool.
A page runs in the viewer's browser or desktop app. It reads and writes Seed records as the viewer, with seed.directory, seed.resource, and seed.publishDocument(recordUrl, {name, metadata}) to create or edit a record. It calls the app's tools with seed.app.call and reads the public config with seed.app.context(). See page.
A trigger under an app calls one of its tools. Scheduled work that reads or writes the app's data, such as a daily digest, is an agent's trigger: the agent reads the records, calls the tools and publishes the result. See trigger.
Where an app's data lives
The app owns its data model:
Type documents live at <app>/types/<type>.
Collections live at <app>/<collection>, with childAttributesSchema set to the type.
Records are children of their collection.
The app names each collection in metadata.publicConfig, for example {"articles": "hm://…/reading-list/articles"}. Its pages (seed.app.context()) and tools (ctx.publicConfig) then find the collections without hard-coded addresses. These documents are not cards in the app. Only tools, pages and triggers are.
Apps and agents
An agent is a document too, typed hm://hyper.media/agent. It hosts children the same way an app does. A tool, page or trigger written directly under an agent's document is listed there by a card embed, and the same code reads the list. Three things differ:
An agent's tools need no run step. They run whenever the agent is mounted on its server.
An agent's trigger can start a session with the agent instead of calling a tool. An app's trigger must call a tool.
An app written directly under an agent's document is listed on the agent like its tools, pages and triggers.
A tool or a trigger must live directly under an app or an agent. The server refuses one written anywhere else. A page can also stand alone as an ordinary document, without a host and without tools to call.
See also
Agent, the other host of tools, pages and triggers.
Building an app for the steps in the desktop app and for agents.
The app environment, the program that runs apps.
Custom pages for building an app's interface.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime