Hometether docs
v1.0.0
Get help
● Set up

Configuration
every setting, where it lives.

Three places hold settings: the server's .env file, build-time values in the app, and the operator console. This page lists the first two.

.envbrand.dartdart-define

01Server environment variables

Copy server/.env.example to server/.env. Never publish this file.

NameDefaultPurpose and where to get it
ADMIN_SECRET_KEYa generated file next to the databaseEncrypts the store keys saved in the console. Make one with openssl rand -hex 32. Back it up: without it the saved keys cannot be read.
ADMIN_SETUP_TOKENa one-time code printed in the logThe code that creates the first console owner. Make one with openssl rand -hex 24 or leave empty. Remove it after the owner exists.
PORT8787HTTP port (the WebSocket relay uses the same port).
DATABASE_PATHdata/hometether.sqliteThe SQLite file. The console keeps its own file beside it. In Docker it is /app/data/hometether.sqlite.
TRUST_PROXY_HOPS0How many reverse proxies you control in front of the server. Use 1 behind Caddy or nginx. Wrong values make rate limits and sign-in limits see the wrong address. See Relay.
ADMIN_DEMO_PASSWORDunsetOnly for a public read-only demo console. Leave empty on a real install.

02If you lose or change ADMIN_SECRET_KEY

The key locks the secrets you paste into the console (the App Store key and the Google Play service account). It is never sent anywhere.

  • If you lose it: the saved store credentials cannot be read again. The console and the app keep working; only server-side purchase checking stops. Set a new key, restart, and enter the store credentials again. If you used the generated key file instead of the variable, copy that file with the database when you move or restore the server.
  • Never put the key in the app or in version control. It belongs in the server's environment only.

03App build-time values

ValueWhereMeaning
API_BASE_URL--dart-define=API_BASE_URL=https://... on flutter run and flutter buildYour server's origin (https, no trailing path). Empty means no server: the parent's own remote and the guided fixes work, remote help is off.
Brand, links, product idsapp/lib/brand.dartSee Rename.

With a server, the app loads GET /v1/config (cached 5 minutes, with an ETag). Values you set in the console override the matching values in brand.dart. Missing keys fall back to built-in defaults. The relay is on the same address at wss://your-server/v1/relay, unless you set a different public relay address in the console.

04Server calls the app makes

CallWhen
GET /v1/configPublic, no login. Brand, paywall, features, relay limits, supported TV text, guided fixes, announcement, update rule.
POST /v1/pingOnly if the user turned on "Share anonymous usage counts" in Settings (off by default).
POST /v1/purchases/verifyOnly if you switch verification on. Otherwise the server answers 501 verification_off.
POST /v1/pairing, POST /v1/pairing/claim, GET|DELETE /v1/pairing/helpers..., DELETE /v1/pairing/selfPairing a helper with a parent, listing and removing helpers.
GET /v1/relay (WebSocket)The relay.

All /v1 HTTP routes are limited to 60 requests a minute per address (answer 429). Request and answer shapes are in contract/CONTRACT.md.