Environments
This page describes the five setups the app environment runs in, from the developer stack to the servers Seed hosts and a server you host yourself, and the settings each one uses.

The app environment, the server behind Seed Agents, is the same program everywhere. What changes is what starts it, which port it uses, which site it reads and writes through, whether it can run code and search the web, and how it is updated.

There are five setups: the dev stack, the desktop app built by CI, the desktop app built on your machine, the servers Seed hosts, and a server you host yourself. The servers Seed hosts are three deployments: production, staging and dev.

The first thing to check, in any setup: /api/health on the running server shows its version, the HM server it uses, and whether code execution and web tools are on.

This page says which settings each setup uses, and why. Configuration is the full list of settings. A server you host yourself has its own page: self-hosting an app environment.

The five setups side by side:


1 · dev (./dev up)

2 · CI-built desktop apps

3 · ./dev build-desktop

4 · hosted remotes

5 · self-hosted remote

Process

bun --watch under a watcher

compiled binary, app-spawned

compiled binary, app-spawned

Docker container

Docker container

Port

3051 (from .env.vars)

3050 (app default)

3050 (app default)

3050 behind Caddy 443

operator's choice

HM API / IPFS

bridge :58004 / daemon :58001

app bridge / app daemon

app bridge / app daemon

hyper.media or dev. (both)

operator's endpoint(s)

Code exec

host microVMs (msb)

embedded msb runtime

embedded msb runtime

staged msb + /dev/kvm

needs KVM

web_search and crawler

Docker compose backends

none (unless configured)

none (unless configured)

SearXNG and Crawl4AI on a private host

optional compose backends

Updates

file-watch restart

app release cycle

rebuild

Watchtower auto-pull

operator pulls

1. Dev mode: ./dev up

This is the developer stack. mprocs runs one pane for each process. The agents pane runs cd apps && bun run dev. That command runs bun --watch src/main.ts under a watcher, scripts/watch-file-deps.ts at the root of the repository (called as bun ../scripts/watch-file-deps.ts).

The watcher runs bun install again and restarts the server when a file: dependency such as apps/protocol changes. While you edit the protocol a lot, the server restarts often, and each restart stops the runs in progress. See development.

The settings come from direnv (.env.vars). They are what makes dev differ from the built-in defaults:

    SEED_APPS_HTTP_PORT=3051: dev does not use the default 3050, on purpose. The desktop app starts its packaged binary on 3050, so an old packaged binary cannot answer in place of the dev server. If something else holds the port, lsof -nP -iTCP:3051 -sTCP:LISTEN names it.

    SEED_APPS_HM_SERVER_URL="$DESKTOP_API_HTTP_URL" (http://localhost:58004): requests such as ListEvents, Resource and PublishBlobs go to the desktop app's /api/* bridge, which speaks DAG-CBOR (Seed API). The daemon's own port speaks gRPC-web and refuses these requests: 405 for query GETs, 415 for CBOR actions.

    SEED_APPS_IPFS_SERVER_URL="$DAEMON_HTTP_URL" (http://localhost:58001): file reads from /ipfs/<cid> go to the daemon, because the desktop bridge serves only /api/*. Publishing a file does not use /ipfs/file-upload. The server cuts the bytes into UnixFS pieces and sends them with PublishBlobs to the HM API. Both addresses reach the same local desktop node, never the public gateway. So dev agents see what you publish in the dev app.

    SEED_APPS_DOCS_ACCOUNT_FILE="$WORKSPACE/hypermedia/.dev/account": the hm-sync pane writes the account of its dev key to this file, and the server reads hm://hyper.media as that account. So dev agents read the knowledge base, and the default Agent Guide, from your working copy of hypermedia/. The links they write name that account too, so a link in a dev agent's reply opens your dev site, not the published docs. Until hm-sync has run once, those reads fail.

    SEED_APPS_DEFAULT_PROMPT_URL: the Agent Guide document that new agents embed as their system prompt.

    VITE_DESKTOP_DEFAULT_APPS_URL=http://localhost:3051: how the dev desktop app finds this server. It connects to it and does not start its own binary. See the order in setup 2.

    The dev script in apps/package.json sets the rest: SEED_APPS_SUBSCRIPTION_AUTH=true, SEED_APPS_SEARXNG_URL=http://127.0.0.1:8899, SEED_APPS_CRAWLER_URL=http://127.0.0.1:11235 and SEED_APPS_CRAWLER_TOKEN=dev-crawl-token.

Docker is available here. The backends pane of mprocs runs SearXNG and Crawl4AI from apps/dev/web-backends/docker-compose.yml. Their logs show in the pane, and they stop when mprocs quits. With them, web_search works in dev, and web reads can fall back to a browser.

Code execution does not use Docker. The microsandbox runtime (msb, libkrun) runs microVMs directly on the host. In dev on a Mac it uses Hypervisor.framework. The microsandbox npm package under apps/node_modules carries the runtime. On first use, msb downloads the sandbox images (python, and oven/bun for the ts runtime) into ~/.microsandbox/, so the first execution is slow. Every copy of msb on the machine shares that one directory; the code execution backend page says why that matters.

Data lives in apps/data/: agents.sqlite and one state directory per agent. Git ignores it, and it stays across restarts. See persistence.

2. Local app environment inside CI-built desktop apps

The desktop app ships its own app environment. In CI (dev-desktop.yml for dev builds, release-desktop.yml for releases), each platform runner executes:

cd apps bun install --frozen-lockfile bun scripts/build-binary.ts --target=<llvm-triple> --smoke

build-binary.ts makes one binary file with bun build --compile, in plz-out/bin/apps/. Two checks keep a broken app environment away from people's machines:

    forge.config.ts packs the binary as an extraResource and fails the CI build when it is missing. So a desktop build cannot ship without its app environment.

    --smoke starts the compiled binary and calls /agents/api/health. So a binary that compiles but cannot start fails in CI.

The microsandbox package cannot go inside the compiled binary, because it has a native binding, the msb helper and libkrunfw. The build puts it in a node_modules/ directory next to the executable. When the server runs, it points MSB_PATH and MSB_LIBKRUNFW_PATH at that copy.

    On macOS the msb binary must be signed with the com.apple.security.hypervisor entitlement, or every sandbox fails to start. osxSign.binaries in forge.config.ts does this for each binary.

    On Windows, execution needs the Windows Hypervisor Platform feature. When it is off, the desktop app answers the execute switch with setup instructions.

When the app runs, it finds its app environment in this order (agents-server-process.ts):

    SEED_NO_APPS_SPAWN is set (or the older SEED_NO_AGENTS_SPAWN): the app never starts a server. It talks only to the remote servers it is configured with.

    SEED_APPS_SERVER_URL is set (or the older SEED_AGENTS_SERVER_URL): the app connects to that URL, trying again if needed, and starts nothing.

    A healthy server already answers on the default port: the app connects to it. This is how the dev app uses setup 1.

    Otherwise, if the agentsLocalServer setting allows it, the app starts the bundled binary on the first free port, counting up from the default. The setting allows it when it is on, or when it is unset and an earlier build left a database; see the desktop UI page. The app passes --hm-server-url=${API_HTTP_URL} and --ipfs-server-url=${DAEMON_HTTP_URL}. The first is the app's /api/* bridge, and the second serves file reads from /ipfs/*. Both lead to the app's own local daemon. So the server inside the app reads and writes through the same node the person sees, never through a public gateway.

How this differs from dev:

    There is no Docker, so there is no SearXNG and no Crawl4AI. A web_search call fails unless the person configures a remote backend.

    There is no watcher. Updates come with new releases of the app.

    Data lives in the app's userData directory, outside the repository.

3. Local desktop builds: ./dev build-desktop

This is the same packaging that CI does, run on your machine. The repository's ./dev script runs cd apps && bun install && bun run build:binary before it calls forge. Forge only copies what is already in plz-out/bin/apps/, so without that step it would pack an old binary and say nothing.

Everything in setup 2 applies here: the binary inside the app, the msb runtime beside it, the entitlements, no Docker, and an HM URL that leads to the app's daemon. Two more things can go wrong on your machine:

    The renderer build needs a large JavaScript heap, about NODE_OPTIONS=--max-old-space-size=8192. desktop:make can exit with 0 even when it ran out of memory. So check that the built app exists; do not trust the exit code.

    An app you built starts its binary on the default port 3050, but first it connects to any healthy server it finds. A running ./dev up stack (port 3051, through VITE_DESKTOP_DEFAULT_APPS_URL) wins in the dev app. The binary of an older installed app can hold a port, and the new build then connects to it. When in doubt, /api/health reports the version of the server that answers.

4. Hosted remotes: production, staging, and dev

This section describes the servers Seed hosts. Their setup lives in another repository, so this repository cannot confirm it, and it can change.

Three Ubuntu virtual machines on OVH/OpenStack run the hosted app environments:

    sae-prod runs production alone.

    sae-dev runs staging and dev.

    sae-services runs the web research backends for all three, on a private network.

The Terraform Cloud workspace SHM-Agentic manages them. It is in the infrastructure repository (mintterteam/infrastructure on GitHub, usually checked out as SeedInfra; stack seed_infra/agentic). Terraform sets up plain Docker hosts. What runs on each is defined by the compose file Terraform writes to /opt/sae/docker-compose.yml.

The three deployments differ mainly in two ways: which image tag they follow, and which HM network they read.

Hostname

Container

Image tag

Code

Data

apps.seed.hyper.media (on sae-prod)

agents-stable

:latest

newest release

mainnet

staging.apps.seed.hyper.media (on sae-dev)

agents-staging

:dev

main

mainnet, via staging.hyper.media

dev.apps.seed.hyper.media (on sae-dev)

agents-dev

:dev

main

devnet

Clients do not use these host names. They reach each deployment on the origin of its gateway: https://hyper.media/hm/api/apps, https://staging.hyper.media/hm/api/apps and https://dev.hyper.media/hm/api/apps. Those origins pass the requests on to the host. The older *.agentic.seed.hyper.media names lead to the same hosts, for clients that saved them.

Staging is the last check before a release. It runs the same code as dev on production data. So you can test a change on real mainnet content before a release tag moves that code to agents-stable. Dev keeps devnet data, which is the right place while a change may still write wrong data.

Each container has its own agents-*-data volume, and this matters. The activity monitor polls only for accounts that have enabled triggers in its own database. So three servers that read the same feed do not react to each other's agents. If you copied the production database into staging, both would fire on the same mention and answer twice.

The stack:

    Caddy (caddy:2) on each host handles TLS on ports 80 and 443, and passes each hostname above to its container on internal port 3050.

    agents-stable / agents-staging / agents-dev run with:

      SEED_APPS_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. That is a mainnet node that also holds the staging site's own documents, which the hyper.media gateway may not have received. These origins serve both /api/* and /ipfs/*, so SEED_APPS_IPFS_SERVER_URL keeps its default, the same value. Every local setup has a daemon beside the server. The hosted servers have none: they read and write through the public gateway.

      SEED_APPS_PUBLIC_URL set to the gateway in front of it: https://hyper.media/hm/api/apps (stable), https://staging.hyper.media/hm/api/apps (staging), https://dev.hyper.media/hm/api/apps (dev). The gateways pass /hm/api/apps and /hm/api/agents on their own origin, and on *.hyper.media subdomains, to this host. So clients use one host for the Seed API and the app environment.

      SEED_APPS_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_APPS_DOCS_ACCOUNT set to the account of the published knowledge base, so reads of hm://hyper.media find it. The hosted servers set it in their deployment config. The self-hosting compose files default it to the production knowledge base account.

      devices: /dev/kvm:/dev/kvm: hardware virtualization for the execute microVMs. Without the device the service still runs. Health reports codeExec: false with the code kvm-missing, and agents are not offered execute. The host must be an OVH type that exposes KVM.

      Named volumes: agents-*-data:/data holds the SQLite database and the agents' state (the image sets SEED_APPS_DB_PATH=/data/agents.sqlite and SEED_APPS_DATA_DIR=/data). agents-*-msb:/root/.microsandbox holds the sandbox images, so the first execution after a redeploy does not download them again.

      SEED_APPS_SEARXNG_URL and SEED_APPS_CRAWLER_URL pointing at the backends on sae-services, over the private network.

      SEED_APPS_EXEC_WARM_POOL=1 and SEED_APPS_EXEC_CANARY_SECS=300 on production and staging.

    SearXNG and Crawl4AI serve the web tools from sae-services, reachable on the private network only. Web research backends has their settings.

    Watchtower pulls new images by itself. It acts on containers that carry its label, and it checks often. A push of seedhypermedia/agents:latest reaches agents-stable, and a push of :dev reaches both agents-staging and agents-dev, within minutes. Deploying covers the workflows that push the images and the Watchtower rules.

Secrets, such as provider API keys and sign-in credentials, are not in the compose environment. Each account has its own rows in the database, written through the signed SetSecret action and stored encrypted. See security. Subscription sign-in (SEED_APPS_SUBSCRIPTION_AUTH) is off unless a deployment turns it on.

Code execution inside the image. The image carries the microsandbox runtime next to the server code, and the image build proves that the runtime loads. With /dev/kvm passed in and the msb volumes mounted, code runs inside the container. Deploying describes the image, and the code execution backend the host side.

5. Self-hosted remote app environments

You can run the image on your own server. Self-hosting an app environment gives the smallest command that works and the decisions you make. Self-hosting covers running the rest of Seed.

How a client finds an environment's agents

You do not configure a client for any of these setups. A client finds the agents of a space through the space's mount documents, and each mount document names the server its agent runs on. Mounting explains how clients find a space's agents and which agents a reader sees.

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

Unsubscribe anytime