operator.yaml

operator.yaml is the only file you edit. Copy it from scripts/tc-operator/operator.yaml.example, keep it mode 0600, and never commit it — it holds your SMTP password, which is the only secret that lives in it. Every other secret is generated into /etc/trusted-codes/secrets.env.

Required

home_server: node1.example.com
admin_email: ops@example.com

home_server is the node’s identity. It cannot be changed on a running node — see Limits below.

Email

smtp:
  host: smtp.resend.com
  port: 587
  user: resend
  pass: <your API key>
  sender_name: Your Node
  sender_email: '' # defaults to noreply@<home_server>

One provider for all of the node’s mail. See Before you start for the verified-domain requirement, which is the thing that usually goes wrong.

Who May Hold an Account

auth:
  registration_mode: invitation_only

Only invitation_only (the default) and closed are yours to set. You may tighten, never loosen. Open, organic signup is authorised centrally through the node’s signed grant; setting open here is ignored and treated as invitation_only.

Two related questions are not set in this file, and are set in the admin app under Node Settings instead:

1. What happens when one of your members invites somebody who has no account anywhere — refuse, or send them to Trusted Codes to register. Choosing to send them sends the invited person’s email address to Trusted Codes. It is a double gate: the central server must accept offers from your node too, or your member’s invitation simply fails with no reason shown to them.
2. Whether other servers may place invitations on your node for your members. This is your inbound kill switch, and it can be set to deny from any state.

They are deliberately outside this file, because every reload rewrites the federation flags unconditionally — a value set here would silently reset a decision you made later.

Federation Flags

federation: true

federation: true turns on the whole participating set — code_lookup, open_link_claim, invitations, groups and multi_account. Any per-flag key overrides the shorthand.

Two things worth knowing:

• An email transport is a hard prerequisite. With no smtp.host, the installer forces the whole set off and tells you so.
• The example file sets each flag to false explicitly. If you copy it unedited you get a node with federation off, even though a node with SMTP configured otherwise defaults to on. Set them deliberately.

What each surface exposes, and why two of them were security findings, is covered in the Federated server section. Read it before turning them on.

WebFinger discovery is always on. A node has to be discoverable to federate.

Surfaces

Which web surfaces this node serves under your domain. Use block form; the inline my: { enabled: true } form is not parsed.

surfaces:
  admin:
    enabled: true
  my:
    enabled: false
  verify:
    enabled: false
  provider:
    enabled: false
  status:
    enabled: false
  business:
    enabled: false
    # host: verify.example.com   # per-surface domain override

admin is on by default and can never be stopped — it is the recovery surface. Each enabled surface is built on the box and needs its own DNS A record.

Branding

branding:
  product_name: Trusted Codes
  primary_color: '#1a3a5c'
  # logo_url: https://node1.example.com/logo.svg

The name, colour and logo are published in the node’s signed node information and applied to the node’s own content — emails, help, onboarding.

Optional Integrations

Everything here is optional. Leave a key empty and that feature is simply off: the node still runs, and both the install summary and tc-operator status show which integrations are on and which are off. Nothing fails silently. You obtain these keys yourself, for your own deployment; Trusted Codes never sees them.

Integration	Keys	Empty means
MaxMind — geography and fraud scoring on logins and lookups	integrations.maxmind.account_id, license_key	logins proceed unscored, which is fail-open
AI chat	integrations.ai.openai_api_key or gemini_api_key	the assistant is off
Metabase — embedded dashboards in the admin app	integrations.metabase.site_url, embedding_secret	dashboards unavailable

The MaxMind default is worth a second look. For a node that should block logins when scoring is unavailable rather than let them through, there is a separate parameter to set.

Billing and mobile push are central-only and have no setting here.

Push Relay

push_relay_server: app.trusted.codes

A federation server name, not a URL. Your node owns its users’ push tokens, but the shared mobile app’s push credential belongs to Trusted Codes, so your node cannot talk to the app stores’ push services directly. With this set, pushes travel as signed federation envelopes through the relay.

The relay sees a token, a time and your server’s name. Never content. In this version only silent “wake up and sync” nudges travel; the device then fetches and renders the real data from your node. The consequence is real: your users get background sync wakes, not server-pushed notification text. Visible alerts appear when the app comes to the foreground and syncs.

Leaving it unset keeps direct sends, which work until push security is enabled across the platform. If push is down entirely nothing breaks — clients converge on foreground sweeps. Push is never load-bearing in this product.

Applying a Change to a Running Node

sudo scripts/tc-operator/tc-operator reload --config operator.yaml

Think of it as bringing the whole node up to what the file now says. It re-verifies SMTP against the live provider before applying anything, re-renders secrets.env from the file, lets Docker recreate exactly the containers whose settings changed, re-applies the database-side settings (federation flags, surface toggles, branding, portal URLs), re-signs the node’s published information, hot-reloads the proxy and self-tests.

Generated secrets — the JWT keys, the encryption keys, the federation identity — are never rotated by a reload. An unchanged configuration is a no-op, so it is safe to run at any time.

Covered: smtp, auth, integrations, branding, surfaces, the federation flags, push_relay_server, and the registry and grant overrides.

What Reload Will Not Do

• home_server cannot be reloaded. Changing it is a change of identity — DNS, TLS, registry admission. Reload refuses and points you at install.
• admin_email is only partly applied. Reload updates the certificate contact address. A new admin account needs tc-operator add-admin --email <addr>.
• A newly enabled surface is not built. Reload warns and points you at tc-operator service start <surface>, which builds and serves it.
• Reload is authoritative for surfaces. Any ad-hoc toggle made in the admin app since the last reconcile is reset to what the file declares. Install behaves the same way.
• New code and new migrations never travel by reload. That is updating.