The agents service is the program that runs Seed Agents. It stores agents, their sessions and every run in a SQLite database, calls language models, executes tools, watches the Hypermedia network for triggers, and publishes signed blobs through a Seed site. It is a server with no web pages of its own: the desktop app, the web app and the mobile app are its clients. This page describes the software. Seed Agents explains what an agent is and how to use one.
The same build runs in three places. The desktop app ships it as a compiled binary and starts one for you. The hosted servers run it as a Docker image. You can also self-host that image.
Where the code is
agents/, package @seed-hypermedia/agents: a separate Bun workspace. Use Bun commands inside it, never pnpm. It is built on Pi (@mariozechner/pi-ai and pi-coding-agent, pinned to 0.70.x) for model calls and the agent loop, the MCP SDK for connecting to remote MCP servers, QuickJS for scripts, and microsandbox microVMs for code execution. It consumes @seed-hypermedia/client and @shm/shared through file: dependencies, which copy the packages at install time.
Path | What it holds |
|---|---|
| Startup, the HTTP routes and the WebSocket server. |
| Every flag and its environment variable; the top code comment is the configuration reference. |
| The signed action handlers, by far the largest file. |
| Envelope signature checks and capability-based authorization. |
| The run queue and the workflow 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. |
Development has the full code map and the conventions.
How it talks to Hypermedia
The service talks to a Seed site and never to a daemon directly. --hm-server-url names the site, https://hyper.media by default. The service reads through the SDK's createSeedClient against that site's /api/<Key> routes (the Seed API), publishes signed blobs with PublishBlobs, and fetches media from --ipfs-server-url, which defaults to the same origin.
The activity monitor polls that site's activity feed every 5 seconds, 50 events a page and at most 5 pages a poll, to fire comment, mention and site-update triggers. Agents sign with their own keys. A person lets an agent publish in their space by delegating a capability to it. See Seed Agents and security.
How clients talk to it
Route | Purpose |
|---|---|
| The signed action API: every request is a DAG-CBOR envelope signed by an account key or by a key holding a capability for the account. See the signed API. |
| Signed WebSocket subscriptions for live session and run updates. See WebSocket subscriptions. |
| Webhook triggers. |
| Status, build, protocol version, and which optional backends are enabled. |
| Timing diagnostics. |
The message, health, version and perf routes answer both with and without the /agents prefix, so the service can share an origin with a site. The WebSocket and webhook routes exist only under /agents.
Clients and servers deploy separately, and a desktop release keeps talking to hosted servers for weeks. So the wire surface carries a protocol version. Clients send it in the envelope, servers answer in the X-Agents-Protocol header, and a server refuses clients older than its minimum with HTTP 426. CI runs bun run protocol:check to catch breaking changes that did not bump the version.
Storage
One SQLite database, agents.sqlite, plus a data directory for agent state files. The tables fall into these groups: accounts and authorizations; model providers, MCP servers and secrets; agents, collaborators and triggers; sessions, session events and continuations; runs, the run journal and event waits; trigger firings and activity watermarks; tool documents; and drafts. Session events are stored as DAG-CBOR, including full tool inputs. Secrets are encrypted with a key the server generates and keeps in its own server_config table. A copy of the whole database therefore holds everything needed to decrypt them. Persistence describes the tables.
If the stored schema version does not match the code, the server starts in a mode that answers every request with a schema-mismatch error.
Configuration
Each flag has a SEED_AGENTS_* environment variable. Flags win over variables. The most used:
Flag | Default | Meaning |
|---|---|---|
| 3050 | Listen port. Development sets 3051 through |
|
| Bind address. The desktop app passes |
|
| Storage; |
|
| The Seed site to use. |
| unset | Web search and browser-rendered reads; unset disables them. |
|
| Code execution; empty disables it. |
| 8 | Model runs at once. Everything shares one event loop, so size this to the host. |
| 32 | Workflow runs at once. |
| off | Offer "Sign in with ChatGPT"-style provider login. |
|
|
|
Operations lists every flag, the web and execution backends, and diagnostics.
Running it
./dev up # the whole stack; the agents pane runs on :3051 with hot reload
cd agents && bun run dev # the server alone, with SearXNG and Crawl4AI expected locally
cd agents && bun check && bun test
cd agents && bun run test:build # the compiled binary boots./dev up also starts the web backends from agents/dev/web-backends/docker-compose.yml: SearXNG on 127.0.0.1:8899 and Crawl4AI on 127.0.0.1:11235. When the copied frontend/packages/* change, the dev script reinstalls them and restarts the server, so they do not go stale.
Deployments
In the desktop app. bun run build:binary compiles the server with bun build --compile into plz-out/bin/agents/seed-agents-<platform>, and the desktop app ships that folder as a resource. At startup the app skips the server if SEED_NO_AGENTS_SPAWN is set, attaches to SEED_AGENTS_SERVER_URL if given, attaches to a healthy server already on the default port (the ./dev up case), and otherwise spawns the binary on the first free port from 3050. The spawned server keeps its data in the app's user data folder under agents/, uses the desktop API bridge as its site and the daemon's HTTP port for /ipfs, and has subscription login on.
Hosted. Images are seedhypermedia/agents:dev, built from main, and seedhypermedia/agents:latest, built on release. A Watchtower container on the agents host redeploys when a tag is pushed, so pushing latest is a production deploy.
Server | Image | Site it uses |
|---|---|---|
|
|
|
| a |
|
|
|
|
Self-hosted. Run the image with a volume on /data, a model provider configured by each account, and --hm-server-url pointing at your site. Environments explains how clients choose a server and how a site advertises one with the agentServerUrl metadata key.
Working with it
In the Seed app
The Agents section of the desktop app talks to the bundled local server by default and can add hosted or self-hosted servers. The web app's /hm/agents page and the mobile app use the hosted server unless configured otherwise.
CLI
SDK
Web API
Agents
This service 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 Building agents on Seed.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime