Self-host runtime (installer vs runner)

Happier currently supports three different self-host “shapes”:

1. a managed install (service + config) driven by happier relay host …
2. a Docker image that bakes verified server-runtime + UI-web artifacts into the image
3. a runner that downloads/verifies artifacts on startup and starts the server process (@happier-dev/relay-server)

They are complementary, but they are not the same thing.

For a complete “what updates automatically vs manually” matrix across all shipped assets (desktop/mobile/web, CLI installers, Docker images, and runners), see: Updates.

Option A: Managed self-host install (recommended when you want a service)

Use happier relay host install when you want:

• the server installed as a managed service (user/system mode)
• a repeatable install-or-update command for your selected channel

First, install the Happier CLI: see CLI install.

Install locally:

happier relay host install --mode system

Install remotely over SSH:

happier relay host install --ssh user@host --mode system

After install, you manage it with:

happier relay host status
happier relay host start
happier relay host stop
happier relay host restart

To update, rerun happier relay host install (it installs or updates to the latest version in that channel).

Auth compatibility during this update

Keep HANDY_MASTER_SECRET unchanged. Persistent auth tokens and encrypted server data are both derived from it, so rotating it is not an auth-repair procedure and can make existing data unreadable.

When updating from a preview relay that used Bun 1.3.5, stop or drain every old relay process before starting the new version. Do not run old and new relay binaries behind the same endpoint during the rollout: the corrected version accepts both the canonical historical key and the Bun-retry key, but an old process may reject tokens newly issued with the canonical key. A complete restart removes that mixed-version direction while preserving existing sessions.

Option B: Docker image (recommended starting point)

The happierdev/relay-server image is built from the same signed server-runtime and UI-web release artifacts, but they are fetched and verified during the Docker image build. The running container starts the embedded happier-server binary directly.

This is ideal when:

• you run the server in Docker, Compose, Nomad, or Kubernetes
• you want image-pull based updates
• you do not want the container to download new application artifacts on every restart

See: Docker.

Option C: Runner (@happier-dev/relay-server)

The relay server package is a server runner:

• it fetches the server runtime by rolling tag (server-stable / server-preview / server-dev)
• verifies and extracts it into a cache
• optionally fetches the UI web bundle (ui-web-stable / ui-web-preview / ui-web-dev)
• sets HAPPIER_SERVER_UI_DIR (if UI is enabled)
• then starts the extracted happier-server binary

This is ideal when:

• you already have a process supervisor
• you want updates to happen on restart (no managed install / no scheduler)
• you do not want hstack installing services/timers/tasks on the host

Example (local runner):

npx --yes --package @happier-dev/relay-server happier-server --help

Important: because this is a runner, happier relay host … service controls do not apply to it.

Choosing between them

• If you want a service and managed lifecycle → use Option A.
• If you want a self-contained container image → use Option B.
• If you already have a process manager and want artifact downloads on restart → use Option C.

If you’re unsure, start with Docker and switch to a managed install later.