The app environment is the server that runs Seed Agents and apps. People do not open it directly. They use it through the desktop app, the web app and the mobile app, which are its clients. It is a Bun server with one SQLite database and no web pages of its own.
This page is the map of the program. Other pages cover the rest:
Seed Agents explains what an agent is and how the runtime behaves.
Operating an app environment is the starting point for running a server.
Development is the guide to changing the code.
Where the code is
The code is in apps/, package @seed-hypermedia/apps. It is a separate Bun workspace, so use Bun commands inside it and never pnpm. It is built on these parts:
Pi: @earendil-works/pi-ai for model calls and @earendil-works/pi-durable for the agent loop. Both are pinned to an exact version in apps/package.json.
The MCP SDK, to connect to remote MCP servers.
QuickJS, to run scripts.
microsandbox microVMs, to run code in a sandbox.
@seed-hypermedia/client and @shm/shared, two of the shared packages. They are file: dependencies, so Bun copies them at install time.
Path | What it holds |
|---|---|
| Startup, the HTTP routes and the WebSocket server. |
| Every flag and its environment variable. Configuration is the reference. |
| The signed action handlers, by far the largest file. |
| The per-session Pi Durable store the model turn runs on. |
| The signature check on each request, and authorization by capability. |
| The run queue and the script engine. |
| Trigger monitors. |
| MCP client, web search and read, sandboxed execution. |
| The schema and its version check. |
|
|
| The client side: the signed client, React Query models and chat UI used by desktop, web and mobile. |
Code map has the file-by-file map, and Development has the conventions.
How it talks to the daemon
How clients talk to it
A client holds one base URL for a server. The API has one main prefix and two older forms. The server answers all three.
Base URL a client holds | Paths |
|---|---|
| The main prefix: |
| The same routes under the older prefix, for released clients and webhook URLs that name it. |
| The oldest form: |
message is the signed action API. Every request is a DAG-CBOR envelope. An account key signs it, or a key that holds a capability for the account. ws carries signed live subscriptions.
The prefix lets a site's reverse proxy send one path to the server. So the server can share an origin with a site.
Three pages hold the reference: Endpoints and health has the full endpoint table, The signed API has the actions, and WebSocket subscriptions has the events.
Clients and servers are released separately, and a desktop release keeps talking to hosted servers for weeks. So every message carries a protocol version:
A client sends its version in the envelope.
A server answers with its version in the X-Agents-Protocol header.
A server refuses a client older than its minimum with HTTP 426.
CI runs bun run protocol:check to catch a breaking change that did not raise the version.
Configuration
Each flag has a SEED_APPS_* environment variable. The server also reads the older SEED_AGENTS_* name. A flag wins over a variable. src/config.ts is the source.
The server listens on 3050 by default and on 3051 in development. The port table has the other programs' ports. Configuration lists every setting, and operating an app environment routes to the backends and the diagnostics.
The server stores everything in one SQLite database, agents.sqlite, plus a data directory for agent state files. Persistence describes the tables.
Running it
./dev up # the whole stack; the agents pane runs on :3051 with hot reload
cd apps && bun run dev # the server alone, with SearXNG and Crawl4AI expected locally
cd apps && bun check && bun test
cd apps && bun run test:build # the compiled binary bootsDevelopment has the rest of the commands, the local URLs and the test map.
How it ships
The same build runs in three places.
In the desktop app. bun run build:binary compiles the server with bun build --compile into plz-out/bin/apps/seed-apps-<platform>. The desktop app ships that folder as a resource. The desktop app does not start the server by default. At startup the app goes through these steps and stops at the first one that applies:
SEED_NO_APPS_SPAWN is set: no local server.
SEED_APPS_SERVER_URL is set: attach to that server.
A healthy server already answers on the default port: attach to it. This is the ./dev up case.
The agentsLocalServer setting is on, or it was never set and a local database from an earlier run exists: spawn the binary on the first free port from the default.
If no step applies, no local server runs and the app uses the hosted one. The switch under Settings > App environments changes the setting. A server that the app spawns is set up like this:
It keeps its data in the app's user data folder, under agents/.
It binds 127.0.0.1.
It has subscription login on.
Hosted. The image is published under two names, seedhypermedia/apps and seedhypermedia/agents. The tag dev is built from main, and the tag latest is built on release. A Watchtower container on the agents host redeploys when a tag is pushed, so pushing latest is a production deploy. Clients reach each hosted server on its site's own origin, for example https://hyper.media/hm/api/apps. The gateway proxies /hm/api/apps to the host the server runs on, also on *.hyper.media subdomains. So the Seed API and the app environment share one host.
Self-hosted. Run the image with a volume on /data and with --hm-server-url pointing at your site. Each account sets up its own model provider. Running your own app environment has the steps.
Environments describes each of these in full, the hosted servers, and how a client chooses a server.
Working with it
In the Seed app
The desktop app talks to the hosted server by default, and hosted or self-hosted servers can be added in Settings. The web app's agent pages under /hm/agents/ and the mobile app use the hosted server unless configured otherwise. Agents in the app describes the screens.
CLI
SDK
The SDK builds the blobs that agents publish. The agents client itself is in @shm/ui/agents, and the wire types are in @seed-hypermedia/apps-protocol. Neither is published to npm under that name. To use them from your own app, install @seed-hypermedia/apps-ui, which bundles both. See Embedding the agents UI.
Seed API
Agents
This server is the runtime for Seed Agents. External agents such as Claude Code do not run inside it. They use the CLI and the Seed API, as described in Using Seed from your own agent.
See also
Seed Agents, the concepts: what an agent is and how the runtime behaves.
Operating an app environment, Configuration, Environments and Persistence, for running it.
Development and Code map, for changing it.
The signed API and WebSocket subscriptions, for clients.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime