App
An app is a document typed hm://hyper.media/app that lists its tools, pages and triggers with card embeds, and that an app environment runs for everyone who uses it.

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:

    Tools are functions that run on a server.

    Pages are HTML interfaces that run in the viewer's client.

    Triggers are rules that call a tool when something happens.

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

type

hm://hyper.media/app

name, summary

the app's name and description

homePage

the hm:// URL of one of its own pages, shown when the app opens

publicConfig

settings every page and tool of the app can read, such as the addresses of its collections

publicConfigSchema, privateConfigSchema

the schemas of the public config and of the private config

appEnvironmentUrl

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

Do you like what you are reading? Subscribe to receive updates.

Unsubscribe anytime

People