Docs
Relay management
The app ships with working servers, but every one of them can be replaced. Server mode decides which servers are eligible; the per-category lists decide which specific ones get used.
Server mode
One global setting, found under Settings → Servers & relays. It applies to every category at once.
| Mode | What it does | Pick it when |
|---|---|---|
| Default | Only the built-in servers. The list is locked — you cannot add, edit or delete anything. | You just want it to work. |
| Default + custom | Built-in servers plus your own. Everything enabled is in the pool. | Adding your own capacity without giving up the fallback. |
| Full custom | Only your own servers. Built-ins stay visible but greyed out as inert fallback. | Self-hosting; you do not want traffic on anyone else's relays. |
Changes take effect immediately — there is no restart, and the call engine picks up new TURN servers on the spot.
Full custom is a soft guarantee
This is the part worth reading twice. If a category has no usable custom server, the app falls back to the built-ins rather than letting chat break:
The same safety net applies in reverse, so a misconfigured list can never leave you with no servers at all. Disabled rows are never eligible in any mode.
Service categories
Servers are grouped by role, and each group is chosen independently. A category can have several servers; the one marked default is used first.
| Category | Port | Role |
|---|---|---|
| Routerrequired | 5223 | Message queues. The one category you cannot operate without. |
| File relayrequired | 5443 | Images, video, voice notes and documents. |
| Entry | 5223 | First hop for 2-hop routing. Optional — no default means direct. |
| Directory | 5663 | Opt-in @username lookup. Defaults to the HTTPS-:443 form. |
| TURN | 3478 | Relays call and Etoki push-to-talk audio when peer-to-peer fails. Needs its shared secret. |
| Bot manager | — | A directory alias (@bot), not an etoki:// address. |
Per-server controls
- Enabled — off takes the server out of the pool without deleting it.
- Set default — the preferred server for that category.
- HTTPS :443 — switches that same server to its TLS-camouflage address. It is a transport toggle on one row, not a second server. Directories ship with it on, because mobile carriers routinely block
:5663. - Health check — probes the server and reports reachability and latency. Use it after adding anything.
The entry hop
The Entry category is how 2-hop routing is configured, and it is the one category where having no default is a valid choice:
- An entry server selected — your traffic reaches the chat router through it. The router never sees your IP; the entry never sees your queue IDs or message contents.
- None (direct) — connections go straight to the chat router, which then sees your IP. Faster, less private.
Pointing the app at your own servers
After following the VPS setup, you will have one etoki:// address per service. Add them in this order:
- Switch to Default + custom first — not Full custom.
- Add your router, run its health check, then set it as default.
- Add your file relay and directory the same way.
- Add your TURN server with the
TURN_SECRETfrom the installer. Without the secret it cannot issue credentials. - Optionally add a second server as your entry hop.
- Only once every category shows healthy, switch to Full custom.
Things that catch people out
- Relay lists are per profile. A second profile gets its own copy seeded from the built-ins.
- The bot manager is a directory alias (
@bot), so it only resolves if a directory holding that registration is reachable. - Deleting a built-in is not possible; disable it instead.
- Existing conversations keep the queues they were created on. Changing your router affects new connections, not old ones.