The app environment
The app environment is the server that runs Seed Agents and apps, and this page says where its code is, how clients reach it, how it ships, and where to read more.

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:

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

src/main.ts

Startup, the HTTP routes and the WebSocket server.

src/config.ts

Every flag and its environment variable. Configuration is the reference.

src/api-service.ts

The signed action handlers, by far the largest file.

src/durable-session.ts

The per-session Pi Durable store the model turn runs on.

src/auth.ts

The signature check on each request, and authorization by capability.

src/runs.ts, src/workflow-*.ts

The run queue and the script engine.

src/activity-monitor.ts, src/activity-triggers.ts, src/schedule-*.ts

Trigger monitors.

src/mcp.ts, src/web-tools.ts, src/code-exec.ts

MCP client, web search and read, sandboxed execution.

src/sqlite-schema.sql, src/sqlite.ts

The schema and its version check.

protocol/

@seed-hypermedia/apps-protocol: the wire types shared with clients, PROTOCOL.md and the surface.json snapshot.

frontend/packages/ui/src/agents/

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

The app environment never talks to a daemon directly. It talks to a Seed site, and the site talks to its daemon. --hm-server-url names the site, which is https://hyper.media by default. The server does four things with that site:

    It reads through the SDK's createSeedClient, which calls the site's /api/<Key> routes. These routes are the Seed API.

    It publishes signed blobs with the PublishBlobs action.

    It fetches media from --ipfs-server-url, which defaults to the same origin.

    It polls the site's activity feed to fire triggers.

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

<origin>/hm/api/apps

The main prefix: /message, /ws, /webhooks/<triggerId>, /health, /version, /perf, /metrics. GET <origin>/hm/api/apps itself lists the apps running on the server as plain JSON.

<origin>/hm/api/agents

The same routes under the older prefix, for released clients and webhook URLs that name it.

<origin> alone

The oldest form: /api/message, /agents/ws and /agents/api/*.

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 boots

Development 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 uses the desktop app's API bridge as its site, and the daemon's HTTP port for /ipfs.

    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

The CLI has no agents commands. Agents use the same Seed API the CLI uses, so anything an agent publishes can be read with seed-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

The server's own API is the signed action API above. It is separate from the Seed API. For Hypermedia reads and writes, the server is an ordinary client of a site's /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

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

Unsubscribe anytime

Attributes
name
The app environment
summary
The app environment is the server that runs Seed Agents and apps, and this page says where its code is, how clients reach it, how it ships, and where to read more.