An enterprise node is Seed for one organization. It is one server with one space. Only the people the organization invites get an account. The node makes no peer-to-peer connection to the public network; it reads public content from other spaces over HTTPS (see below). The deploy script sets it up with its second profile, --profile enterprise.
The first thing to check on a running node is seed-deploy doctor. It tests the containers, the sign-in check and the isolation.
This page covers what the profile runs, how people get in, how the organization's space is made, and what the node may talk to. Read self-hosting first. Everything there about DNS, the install directory, seed-deploy and backups applies here too.
Installing
Start the script with --profile enterprise:
curl -fsSL https://deploy.seed.hyper.media | sh -s -- --profile enterpriseThe script then asks its questions; see The wizard. When there is no terminal, for example over ssh host 'curl … | sh -s -- …', pass the answers as flags and add --yes:
seed-deploy deploy --profile enterprise --hostname https://example.org --tag latest --email you@example.org [--agents] [--notify] --yesWith --notify and no email relay (below), give the SMTP account in SEED_SMTP_HOST, SEED_SMTP_USER, SEED_SMTP_PASSWORD and SEED_SMTP_SENDER.
--tag takes any image tag. That includes the cleaned-up branch name that a branch build of the Docker images produces.
What it runs
The compose file is ops/docker-compose.enterprise.yml. All services share one internal network. Only the proxy publishes ports.
Container | Image | Ports on the host | Role |
|---|---|---|---|
|
| 80, 443, 443/udp | TLS, then reverse proxy with the sign-in gate |
|
| none | the web app with |
|
| none | the daemon with |
|
| none | the identity vault, invite-only, served at |
|
| none | optional, compose profile |
|
| none | optional, compose profile |
The metrics profile with Prometheus and Grafana is the same as in the site profile. Every image uses the tag of the release channel. web_image and site_image in config.json replace the web and daemon images, as on a site.
The wizard
The wizard asks these questions. The last column is the flag to use when there is no terminal.
Question | What to answer | Without a terminal |
|---|---|---|
Public hostname | the full URL of the site, |
|
Name of the organization's space | the bare hostname by default |
|
Password for the space's exported owner key | optional; asked on a first run only |
|
Release channel |
|
|
Log level | Info | |
Run agents | no by default |
|
Run notify | no by default |
|
SMTP host, user, password and sender address | asked only when notify is on and no email relay is configured |
|
Contact email | an address for security notices |
|
The vault and the notify service both send mail with STARTTLS on port 587. smtp.port in config.json changes the port.
The wizard does not ask about the network, gateway mode or analytics. The profile turns mainnet off, gateway mode off and statistics off.
The wizard makes four secrets and stores them in config.json:
link_secret: the registration secret that /hm/register uses.
vault_admin_secret: a 40-character bearer token for the vault's admin API.
session_secret: the key the web app signs its session cookie with.
service_secret: what the app environment shows in place of a session cookie, in the header X-Seed-Service-Secret. The app environment reads the site from the server side, for example to notice the mentions that fire its triggers.
seed-deploy config prints the secrets with their values hidden, and the email relay token too.
Email without an SMTP account
The Seed hosting service can give an enterprise node an email relay: an HTTPS address and a bearer token. With the relay configured, the vault sends its verification codes through it, and the notify service sends its notification emails through it.
Each email is one POST <url> with Authorization: Bearer <token> and a JSON body {to, subject, text, html?, replyTo?}. Any 2xx answer means the relay took it. Anything else fails the send. The hosting relay sets the From address itself; this describes the hosted service and can change.
The relay wins over SMTP. So with a relay, you can turn notify on without an SMTP account.
How to set it:
seed-deploy --advanced asks for the two values. The ordinary wizard does not ask, so a relay stays as it is when you reconfigure.
Without a terminal, pass --email-relay-url and --email-relay-token, or set SEED_EMAIL_RELAY_URL and SEED_EMAIL_RELAY_TOKEN in the environment.
The values are stored as email_relay_url and email_relay_token in config.json.
They reach the containers as SEED_VAULT_EMAIL_RELAY_URL/_TOKEN on seed-vault and NOTIFY_EMAIL_RELAY_URL/_TOKEN on seed-notify.
Getting in
Caddy asks the web app whether each request comes from a signed-in member. If not, a browser is sent to /hm/sign-in and an API call gets 401.
In detail: for every request that is not on an open path, Caddy calls /hm/api/session on the web app (forward_auth, with the original path in X-Forwarded-Uri). An answer of 204 lets the request through. Any other answer goes back to the client: a 302 to /hm/sign-in?next=… for a browser, or a 401 for an API call.
These sit behind the gate like the rest of the site:
the daemon's /ipfs/* reads;
the /.metrics pages;
the app environment: /hm/api/apps and /hm/api/agents and everything under them, API and WebSocket.
These paths are open:
Open path | Why it is open |
|---|---|
| the sign-in flow itself |
| the vault, where people sign in |
| calls the sign-in callback makes before a cookie exists; |
| the Seed app and the deploy script use them |
| the deploy script uses them; they demand the vault admin secret |
| outside services call them with the trigger's secret in the path |
| the notify service; it goes straight to |
| the paths older Seed apps call for notify |
| the email notification settings page, reached from a link in an email. A person who follows an email link need not be a member |
static assets | the pages above need them |
The proxy's list is made from the web app's isOpenPath rules in frontend/apps/web/app/require-sign-in.ts, so the two always agree.
Commands
These commands are added to the ones in self-hosting. Running an invite-only vault covers the vault's side of invitations.
Command | What it does |
|---|---|
| Makes an invitation link for one person. It asks the vault's admin API ( |
| Creates the organization's space and registers the site to it. The first deploy does this by itself; use the command when that attempt failed. It is safe to run again: on a registered site it prints the existing account and changes nothing |
| Registers a space that already lives on this daemon. It reads the daemon's peer id from |
| Moves the node to a new hostname. It rewrites |
| Adds these to the usual checks: |
The organization's space
The script creates the space itself, once the health checks of the first deploy pass. So the first person who signs in finds a site, not an empty node.
The script calls POST /hm/api/enterprise-bootstrap on the public hostname, with the vault_admin_secret. It tries again for about half a minute while the web app starts.
The web app makes a key in the daemon's keystore, from a mnemonic it holds only for that request. It publishes the space's home document, signed by that key. The document has the name from the wizard or --site-name, the site's address and a welcome paragraph. Then it registers the site to the new account, the way /hm/api/register does.
The answer carries the space's account and the standard .hmkey.json export of its key. The export is encrypted with the owner password when you gave one. The script saves it as owner-key/<accountUid>.hmkey.json in the install directory, readable only by the user who installed. It records the account as owner_account_uid in config.json.
The deploy output ends with the account, the path of the key file, and how to take control of the space. Import the file in one of three ways: in the vault at https://<your-domain>/vault/settings (Import identity in the sidebar; it asks for the password if the file has one), with the desktop app's key import, or with seed-cli key import <file>.
The mnemonic is never written anywhere. The key file is the only copy outside the daemon. After you import it, keep it somewhere safe or delete it. seed-deploy secret prints its path again.
If the attempt fails, the deploy still succeeds and says so. Run seed-deploy bootstrap-space once the site answers.
Changing the hostname
Before you start. Set the hostname before you invite anyone. A passkey (WebAuthn) belongs to the domain it was made on, so a passkey made at the first address does not work at the next one. Password sign-in keeps working: the person signs in with the password and adds a new passkey in the vault.
For a customer's domain, the customer makes an A record for the name (seed for seed.customer.org, or @ for the root) whose value is the server's IP address. Any proxying by the DNS provider must be off. The proxy on the node needs the name to lead to the server, or it cannot get a certificate from Let's Encrypt.
The command. Once the name leads to the server, run:
seed-deploy set-hostname https://seed.customer.orgconfig.json, the Caddyfile and the containers' environment follow the new hostname: SEED_BASE_URL, the vault's relying party, and the agents' site address.
When the containers are healthy, the script calls POST /hm/api/enterprise-site-url with the vault_admin_secret.
The web app republishes the space's home document with siteUrl set to the new address. Only the metadata changes. The owner key in the daemon signs it, in the document's current generation.
The same happens when a reconfiguration changes the hostname (deploy --reconfigure, or deploy --profile enterprise --hostname … --yes).
If the last step fails. The node is up. Run set-hostname again with the same hostname; it tries only the republish. doctor warns as long as the home document and the hostname disagree.
The old hostname. It is kept in redirect_hostnames in config.json. Caddy still gets a certificate for it and redirects it to the new address. So a managed address such as <name>.hyper.media keeps working after the organization's own domain takes over.
The general steps for domains are in custom domains.
What is isolated and how
The node is closed off in these ways:
What | How it is closed |
|---|---|
Peers reaching the daemon | The daemon's libp2p listener is on loopback inside its container, and no port is published |
The daemon reaching peers |
|
A peer address that leaks in | The private testnet name keeps the node off the public network |
The wallet |
|
Telemetry |
|
The web app's calls | It talks only to the daemon, the vault and, when they are on, the notify and agents services on the same server, at |
The hosted services |
|
The vault | It uses the site's domain as its WebAuthn relying party and reaches the daemon over the internal network |
The image already sets SEED_SERVER_MODE=true.
What leaves the server:
email, through your SMTP account or the hosting email relay;
the agents' calls to their model provider, when agents are on.
Caddy limits a request body to 512 MB. Rate limiting needs a Caddy plugin that the stock caddy:2 image does not have, so it is not configured.
The daemon network reference describes these flags.
Public content from other spaces
The daemon never talks to another node. So a document from another space is not on the server. Examples are an embed of a public document, the Agent Guide that the app environment puts in its system prompt, and a directory the agents read.
The web app answers those reads from the public HTTP API of a mainnet node:
The daemon reports Resource, ResourceMetadata or Account as not found, or a Query over one space comes back empty.
The web app checks that the daemon has never seen that account.
The web app sends the same GET /api/<Key> to upstream_api_url and passes the answer on. The default is https://hyper.media. Set it to "" in config.json to keep every read on the server.
Images and files of such documents come the same way, from that node's /ipfs/<cid>.
What this means for privacy:
Nothing is stored on the server, and answers are cached for a minute.
A read inside the organization's own space, or of any account the daemon knows, is never sent out.
What does leave the server is the id of the outside document or image that is read.
The app environment reads through the site, so it gets the same content. hm://hyper.media/... links lead to the Seed knowledge base space (SEED_APPS_DOCS_ACCOUNT).
Updates
On the two usual image channels, an enterprise node installs the same cron job as a site: upgrade then deploy, every ten minutes. On latest it gets each release. On dev it follows main; Seed's own test nodes run this way.
On any other channel, such as a branch's images under test, no cron job is installed. Run seed-deploy deploy by hand to get the compose file and new images. seed-deploy cron installs the automatic update if you want it after all.
seed-deploy backup includes the vault, notify and agents directories, along with web, daemon and proxy. It leaves out owner-key/ on purpose: the exported key is for importing, not for keeping on the server.
Treat a backup with care. It can hold private content of the organization's space, and config.json holds the secrets.
Agents and code execution
With agents on, the node runs its own app environment for members only. Operating an app environment says how to look after it. Code execution in a sandbox needs /dev/kvm on the host and "agents_kvm": true in config.json; see self-hosting. Without it, agents are not offered execute.
Limits
Privacy comes from the node being out of reach. The documents inside it are ordinary public documents.
The host firewall is yours to set up. So is the list of outside addresses the server may call, for the mail relay and the model provider. The script does not configure them.
Backups are not encrypted.
There is no single sign-on in front of the vault.
There is no audit log of sign-ins and capability grants.
A file fetched by /ipfs/* is protected by the sign-in gate only.
doctor fails its isolation checks when the running images are too old to know the isolation flags.
See also
Self-hosting, the site profile and the seed-deploy command
Vault, invite-only mode and the admin API
Notify, the notification service
Daemon network reference, the daemon's flags
Operations, running the app environment the node may include
Privacy, private documents in the protocol
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime