A Seed Agents server runs in five kinds of environment. The hosted remote is one kind, running as three deployments: production, staging, and dev. The binary logic is the same everywhere. The surroundings differ: what spawns it, what it binds, which HM server it reads and writes through, whether code execution and web tools exist, and how it gets updated. This page describes each environment and the configuration that makes it work. The full env-var reference is in operations. This page covers which of those settings each environment uses, and why.
A quick orientation table:
1 · dev ( | 2 · CI-built desktop apps | 3 · | 4 · hosted remotes | 5 · self-hosted remote | |
|---|---|---|---|---|---|
Process |
| compiled binary, app-spawned | compiled binary, app-spawned | Docker container | Docker container |
Port |
|
|
|
| operator's choice |
HM API / IPFS | bridge | app bridge / app daemon | app bridge / app daemon |
| operator's endpoint(s) |
Code exec | host microVMs (msb) | embedded msb runtime | embedded msb runtime | staged msb + | needs KVM |
websearch/crawler | Docker compose backends | none (unless configured) | none (unless configured) | compose-internal SearXNG/Crawl | optional compose backends |
Updates | file-watch restart | app release cycle | rebuild | Watchtower auto-pull | operator pulls |
1. Dev mode: ./dev up
The developer stack. mprocs runs one pane per process. The agents pane is cd agents && bun run dev, which wraps bun --hot src/main.ts in the repo-root scripts/watch-file-deps.ts (invoked as bun ../scripts/watch-file-deps.ts). The watcher re-runs bun install and restarts the server when a file: dependency like agents/protocol changes. During heavy protocol editing it flaps and kills in-flight runs. See development.
Configuration comes from direnv (.env.vars). That layer is what makes dev different from the built-in defaults:
SEED_AGENTS_HTTP_PORT=3051: dev does NOT use the default 3050, on purpose, so a stale packaged binary (which the desktop app spawns on its own default) cannot shadow the dev server. If localhost:3051 ever answers with Unsupported action: ListRuns-class errors, something else claimed the port. Check lsof -nP -iTCP:3051 -sTCP:LISTEN.
SEED_AGENTS_HM_SERVER_URL="$DESKTOP_API_HTTP_URL" (http://localhost:58004): typed Seed requests such as ListEvents, Resource, and PublishBlobs go through the desktop's DAG-CBOR /api/* bridge (Seed API). The raw daemon port is a gRPC-web endpoint and rejects this transport (405 for query GETs, 415 for CBOR actions).
SEED_AGENTS_IPFS_SERVER_URL="$DAEMON_HTTP_URL" (http://localhost:58001): direct /ipfs/<cid> gateway reads go to the daemon, because the desktop API bridge serves only /api/*. File publication does not use /ipfs/file-upload. The service chunks bytes into UnixFS blocks and sends them through PublishBlobs on the typed API. Together these endpoints reach the same local desktop node, and never the public gateway. Content published in the dev app is what dev agents see.
SEED_AGENTS_DOCS_ACCOUNT_FILE="$WORKSPACE/hypermedia/.dev/account": the hm-sync pane writes its dev key's account to this file, and the server resolves hm://hyper.media to it. Dev agents read the knowledge base, and the default Agent Guide, straight from your working copy of hypermedia/. Until hm-sync has run once, those reads fail.
SEED_AGENTS_DEFAULT_PROMPT_URL: the Agent Guide document new agents embed as their system prompt.
VITE_DESKTOP_DEFAULT_AGENTS_URL=http://localhost:3051: how the dev desktop app finds this server. It attaches and does not spawn its own binary. See the resolution order in environment 2.
SEED_AGENTS_SUBSCRIPTION_AUTH=true and the web-tool URLs are set by the dev script itself: SEED_AGENTS_SEARXNG_URL=http://127.0.0.1:8899, SEED_AGENTS_CRAWLER_URL=http://127.0.0.1:11235.
Docker is available here, and the backends mprocs pane runs it: SearXNG and Crawl4AI from agents/dev/web-backends/docker-compose.yml, inline. Their logs stream into the pane, and they stop when mprocs quits. That turns on web_search and browser-render escalation in dev.
Code execution does not use Docker. The microsandbox runtime (msb, libkrun) runs hardware-isolated microVMs directly on the host, with macOS Hypervisor.framework in dev. The microsandbox npm package under agents/node_modules carries the runtime. msb pulls sandbox rootfs images (python, and oven/bun for the ts runtime) itself on first use, into ~/.microsandbox/. There are two sharp edges. First, every msb copy on the machine shares that one state directory, and a newer msb that migrates its database silently locks out every older copy (database schema is newer than this msb binary), so keep the dependency pinned exactly. Second, the sandbox image pull makes the first execution slow.
Data lives in agents/data/ (agents.sqlite + per-agent state dirs). It is gitignored and persists across restarts. See persistence.
2. Local agents server inside CI-built desktop apps
The desktop app ships its own agents server. In CI (dev-desktop.yml for dev builds, release-desktop.yml for releases), each platform runner executes:
cd agents
bun install --frozen-lockfile
bun scripts/build-binary.ts --target=<llvm-triple> --smokebuild-binary.ts produces a bun build --compile single-file binary in plz-out/bin/agents/. forge.config.ts picks it up as an extraResource and fails loudly in CI when it is missing, so a desktop build cannot silently ship without its agents server. --smoke boots the compiled binary and hits /agents/api/health, so a binary that compiles but cannot start fails in CI and never reaches user machines.
The microsandbox package cannot live inside the compiled bundle (napi binding, msb helper, libkrunfw). The build stages it into a node_modules/ directory next to the executable, and at runtime the server points MSB_PATH and MSB_LIBKRUNFW_PATH at that staged copy. On macOS the msb binary must be signed with the com.apple.security.hypervisor entitlement (handled per-binary via osxSign.binaries in forge.config.ts), or every sandbox create fails. On Windows, execution needs the Windows Hypervisor Platform feature, and the desktop UI answers the execute toggle with setup instructions when it is off.
At runtime the app resolves its agents server in this order (agents-server-process.ts):
SEED_NO_AGENTS_SPAWN set: never spawn. The app only talks to configured remote servers.
SEED_AGENTS_SERVER_URL set: attach to that URL (with retry) and spawn nothing.
A healthy server already answering on the default port: attach to it. This is how the dev app uses env 1.
Otherwise, if the agentsLocalServer setting allows it (on, or unset with a database left by an earlier build; see the desktop UI page), spawn the bundled binary with explicit --hm-server-url=${API_HTTP_URL} and --ipfs-server-url=${DAEMON_HTTP_URL} flags. The first is the app's typed /api/* bridge. The second serves direct /ipfs/* gateway reads. Both front the app's own local daemon, so the embedded server reads and writes through the same node the user sees, and never through a public gateway.
Differences from dev: no Docker exists here, so there is no SearXNG or Crawl4AI, and web_search is unavailable unless the user configures a remote backend. There is no watcher, because updates come with the app release cycle. Data lives in the app's userData directory, outside the repo.
3. Local desktop builds: ./dev build-desktop
This is the CI packaging path, run locally. The dev script executes cd agents && bun install && bun run build:binary before invoking forge, because forge only copies whatever is already staged in plz-out/bin/agents/. Skipping the step silently packages a stale binary. Everything in environment 2 applies (embedded binary, staged msb runtime, entitlements, no Docker, daemon-backed HM URL), plus two local-only gotchas:
The renderer build needs a large JS heap (NODE_OPTIONS=--max-old-space-size=8192-class). desktop:make has been seen to exit 0 even on a fatal OOM, so check that the artifact exists before trusting the exit code.
A locally built app spawns its binary on the default port 3050, but attaches to anything healthy it finds first. A running ./dev up stack (port 3051 via VITE_DESKTOP_DEFAULT_AGENTS_URL) wins in the dev app, and a stale previously-installed app's binary can hold a port the new build then attaches to. When in doubt, /api/health reports the running server's version.
4. Hosted remotes: production, staging, and dev
One Ubuntu 24.04 VM runs all three hosted agents servers. It is on OVH/OpenStack, managed by the Terraform Cloud workspace SHM-Agentic in the SeedInfra repo (seed_infra/agentic). Terraform provisions a bare Docker host. The service definition is the compose file it writes to /opt/agentic/docker-compose.yml.
The three deployments differ in exactly two ways: which image tag they track, and which HM network they read.
Hostname | Container | Image tag | Code | Data |
|---|---|---|---|---|
|
|
| newest release | mainnet |
|
|
|
| mainnet, via |
|
|
|
| devnet |
Staging is the release gate. It runs the same code as dev against production data, so you can validate behavior on real mainnet content before a release tag promotes that code to agents-stable. Dev keeps devnet data, which is where you want to be while a change may still write nonsense.
Each container has its own agents-*-data volume, and that separation matters. The activity monitor only polls for accounts that have enabled triggers in its own database, so three servers pointed at the same feed stay quiet about each other's agents. If you copied prod's DB into staging, both would fire on the same mainnet mention and answer twice.
The stack:
Caddy (caddy:2) terminates TLS on 80/443 and reverse-proxies each hostname above to its container on internal port 3050.
agents-stable / agents-staging / agents-dev run with:
SEED_AGENTS_HM_SERVER_URL set to https://hyper.media (stable), https://staging.hyper.media (staging), or https://dev.hyper.media (dev). Staging reads through the staging web gateway: a mainnet node that also holds the staging site's own documents, which the hyper.media gateway may not have synced yet. Those origins serve both typed /api/* and direct /ipfs/*, so SEED_AGENTS_IPFS_SERVER_URL defaults to the same value. Unlike every local environment, the hosted servers read and write through the public gateway. There is no co-located daemon.
SEED_AGENTS_DEFAULT_PROMPT_URL naming the Agent Guide new agents embed. Production uses the default, the guide on hyper.media; staging names the staging copy.
SEED_AGENTS_DOCS_ACCOUNT set to the account of the published knowledge base, so hm://hyper.media reads resolve. The repo never names that account. It lives in the deployment config until hm:// URLs resolve domains.
devices: /dev/kvm:/dev/kvm: hardware virtualization for the execute microVMs. Without the device the service runs, but every execution fails 502. This needs an OVH flavor that exposes KVM.
Named volumes: agents-*-data:/data (the sqlite DB + agent state; SEED_AGENTS_DB_PATH=/data/agents.sqlite and SEED_AGENTS_DATA_DIR=/data are baked into the image) and agents-*-msb:/root/.microsandbox (the sandbox image cache, persisted so the first execution after each redeploy does not re-pull rootfs images).
SEED_AGENTS_SEARXNG_URL=http://searxng:8080, SEED_AGENTS_CRAWLER_URL=http://crawl4ai:11235: compose-internal backends.
SearXNG (json format enabled, limiter off, which is safe only because it is never published outside the compose network) and Crawl4AI (version-pinned, because 0.9.0 changed auth defaults, so it must not float to :latest; needs shared memory for Chromium) serve the web tools, internal-only.
Watchtower (label-enabled, short poll interval) auto-pulls the agents images. Pushing seedhypermedia/agents:latest deploys to agents-stable, and pushing :dev deploys to both agents-staging and agents-dev, within minutes. The three GitHub workflows described in operations push the images (release tags to :latest, main pushes touching agents/** to :dev, plus a manual hotfix path), or you push manually via agents/scripts/build-and-push.sh. Make sure the Watchtower container itself has restart: unless-stopped. A crashed auto-updater silently stops all deploys, and so does a stopped one: docker stop on a container with that policy stays stopped across reboots. That is how the host once went four days without a deploy.
Watchtower reads com.centurylinklabs.watchtower.enable from the running container, and ignores the compose file, so editing that label only takes effect after docker compose up -d <service> recreates the container.
Secrets (provider API keys, OAuth credentials) are not in the compose environment. They are per-account rows in the database, written through the signed SetSecret API and encrypted at rest. See security. Subscription OAuth (SEED_AGENTS_SUBSCRIPTION_AUTH) is an explicit opt-in flag wherever it is wanted.
Code execution inside the image. The microsandbox runtime cannot be bundled (native binding + msb + libkrunfw). So microsandbox is external in the server bundle (build.ts), and the Dockerfile stages the package, plus its linux platform package, into /app/node_modules next to main.js (scripts/stage-msb-runtime.ts). This is the same layout build-binary.ts ships beside the desktop binary. The image build runs --exec-selfcheck, so a staging regression fails the build and never shows up as codeExec: false on the servers. Everything else the runtime needs travels inside the bundle, including mermaid and the linkedom DOM shim behind the mermaid check on document writes (src/mermaid-parser.ts, which imports them by literal specifier where the client package deliberately does not); the same selfcheck parses a diagram so a bundling regression fails the build rather than every write that carries one. With /dev/kvm plumbed and the msb cache volumes mounted, executions run in-container. /api/health reports the probe result either way.
5. Self-hosted remote agents servers
Anyone can run the image. The minimal server:
docker run -d --restart unless-stopped \
-p 3050:3050 \
-v seed-agents-data:/data \
-e SEED_AGENTS_HM_SERVER_URL=https://your-site.example \
seedhypermedia/agents:latestWhat an operator must decide, roughly in order of importance. Self-hosting covers running the rest of Seed.
HM API URL. SEED_AGENTS_HM_SERVER_URL must point at an HTTP Seed API that accepts the typed DAG-CBOR /api/* protocol used by createSeedClient: your site, a desktop-style API bridge, or the public gateway. A raw daemon gRPC-web port does not work as this endpoint.
IPFS URL. By default, direct /ipfs/* gateway reads use the HM API origin. If the gateway lives elsewhere, as it does locally where the daemon owns it, set SEED_AGENTS_IPFS_SERVER_URL to that origin. File publication still chunks UnixFS blocks and sends them through PublishBlobs on the HM API. So a self-hosted raw daemon can be the gateway, but SEED_AGENTS_HM_SERVER_URL still needs a compatible Seed HTTP API or bridge.
TLS and hostname. Put a reverse proxy (Caddy, nginx) in front. The desktop and web apps connect over HTTPS, and the signed-envelope API assumes an authentic transport. Either give the service its own hostname, or route /hm/api/agents/* on your site's origin to it and advertise https://<site>/hm/api/agents as the server URL (see operations). CORS is already permissive server-side.
Code execution. Needs KVM (--device /dev/kvm) on a host whose virtualization is exposed. The image ships the microsandbox runtime staged in /app/node_modules, so no custom image is needed. Without KVM the server still runs and /api/health reports codeExec: false (kvm-missing). Or set SEED_AGENTS_EXEC_BACKEND=off to advertise honestly. Persist /root/.microsandbox if you enable it. Set SEED_AGENTS_EXEC_TS_IMAGE= (empty) to withhold TypeScript, or leave the oven/bun default.
Web tools. Optional SearXNG (SEED_AGENTS_SEARXNG_URL) and Crawl4AI (SEED_AGENTS_CRAWLER_URL + SEED_AGENTS_CRAWLER_TOKEN) containers, internal-only, exactly as production wires them. Without SearXNG, agents are not offered the web_search callable.
Subscription OAuth. Off by default. SEED_AGENTS_SUBSCRIPTION_AUTH=true enables "Sign in with ChatGPT". See model providers.
Accounts. The server is multi-account by signature. It trusts any envelope whose signer IS the account, or an authorized signer. There is no allowlist today. A reachable server accepts any self-signed account's agents, so do not rely on obscurity. If that matters, gate reachability at the network layer.
Updates. docker pull on your schedule, or run Watchtower as production does. /api/version tells you what a running server was built from.
Which agents server a client connects to
A space's agents are its mount documents: a document with type: hm://hyper.media/agent and an agentServerUrl (metadata) is an agent, its versionless hm:// id is the agent's id, and the named server must register it under exactly that id. There is no space-level agent registry and no server a space advertises: to find a space's agents a client queries the space's documents for that type (QueryDocuments with a type comparison, useSiteAgentMounts in @shm/ui/site-agents). The query runs on the client after the page is up, so a page never waits on it, and the result is cached like any document listing.
Which servers a client then talks to differs by surface:
The web app and the gateway talk only to the servers those mount documents name, and only about those agents. The assistant panel lists the site's mounted agents and nothing else: no agents from other servers, no orphan agents, and no ListAgents call to any server. The header shows the panel's entry point only to a signed-in reader whose account can see at least one of the site's mounted agents: the owner, an accepted collaborator, or anyone once the agent is public. A mount document the agent is not shared with them through shows nothing, and so does a site with no mounts. The one exception is a reader who owns orphan agents (agents from before agents were documents, still under a legacy id): the client asks the deployment's default server and the servers the site's mounts name for the account's own agents, and while any orphan remains the entry point stays visible with a red dot, so the panel's adopt card can be found. Readers who are not signed in get no entry point, since every request to an agents server is signed; a public agent could open that to them later. The deployment default (SEED_AGENT_SERVER_URL, read on the server and injected into window.ENV) is used for one thing: the server a new agent is created on from a home document's New menu.
The desktop app adds the account's own agents: the app's own local server first (getLocalServerUrl on the platform seam; a space never names it, since only the computer running it can reach it), then the servers the user configured in settings (agent-server-urls, electron-store; seeded with the desktop default from frontend/apps/desktop/src/agents-defaults.ts on first run, and never re-added once the list has been edited, even to empty). The mounted agents of the space on screen lead the picker, labeled with the space's name.
The agents server itself needs no per-client configuration for this. It answers signed requests from any origin (Access-Control-Allow-Origin: *) and identifies callers by their signed account, never by where the page was served.
Which agents a reader of a space sees
A server alone does not reach a reader. ListAgents returns only agents the caller owns or accepted an invitation to, so a visitor asking a space's server for a list gets an empty one. The mount documents are what reach the reader: given an agent's id, the server resolves the owning account itself and answers GetAgent for the owner, an accepted collaborator, or any signed account once the agent is public-read (SetAgentPublicRead; SetAgentPublicChat lets them chat too, see the signed API). Clients fetch each mounted agent by id; one the reader cannot see is left out, and on the agent's own page the reader is told why (not shared with their account, or an invite to accept). Mounted agents are listed in their documents' path order, and the first one is the assistant panel's default context, so someone arriving at a space can open the panel and start chatting without configuring anything.
A space whose mounted agents the reader cannot see offers them no agents at all, and a space with no mounts the same. The web header leaves out the panel's entry point while browsing either, since the panel would only show an empty picker.
An agent's name, icon, and status are read from the agent itself; the document carries the name attribute the agent is named by (see desktop UI).
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime