SolarOS 4.17.7 manual · job

chatd

Local SolarOS chat gateway server. It is useful for testing the chat app or for small trusted local networks.

Usage:

job start chatd [port] [token] [--history path] [--sc2 on|off] [--v1 on|off] [--sc2-id ID]
job start chatd [port] [token] [path]
job stop chatd
job status chatd

Defaults:

Arguments are intentionally flexible. The first numeric argument is the port. The next non-option argument is the optional token. --history or --log selects an optional append-only history dump file.

Examples:

job start chatd
job start chatd 7777 secret
job start chatd 7777 secret --history /.shell/chatd.log

SC2 mini-relay

On builds with SC2 messaging, chatd is also a small SC2 relay on the same port, so a device can be a relay and a client at once. The first line a client sends decides: an SC2 hello goes to the mini-relay, a v1 hello to the v1 server. Legacy v1 stays on by default, as on the self-hosted relay; --v1 off refuses v1 clients (426) and --sc2 off turns the mini-relay off. The token, when set, is also the SC2 admission code for new devices. Rate limits are off, as on the self-hosted relay.

The mini-relay is a fixed-size subset of the relay protocol:

The six connections are held for a bounded time, as on the self-hosted relay:

• One session per device: when a device logs in again, its older session gets 409 replaced and is closed (this also clears a connection left half-open by a network change).
• Keepalive pings are not activity. A session that sends nothing else for 5 minutes gets 408 idle and is closed; the client reconnects and picks up waiting DMs at its next sync. A login has to finish within 30 seconds.
• When all six connections are taken, a new one takes the slot of the session that has been idle longest, if that one has been idle for at least a minute (503 evicted); otherwise the newcomer gets 503 server_full.

Private rooms and other public rooms are refused (501/404); use a full relay for those. All stores live in one PSRAM block (about 135 KiB), so the mailbox and history are lost when chatd stops. Without PSRAM the mini-relay stays off and v1 keeps working. The relay key is created once and kept in the SC2 store (mr/relay), so pinned clients keep trusting it across restarts. chatd logs it at start:

chatd: SC2 relay chatd-1a2b3c4d key=B64 (134 KiB PSRAM), v1 too

Pin it on clients with messages add sc2 NAME chat://IP:7777 [TOKEN] key=B64. The device running chatd can use its own relay through chat://127.0.0.1:7777.

The local chat app can connect with:

chat local
chat 127.0.0.1:7777

On another SolarOS device or host on the same network, use the server IP:

chat 192.168.1.113:7777

Notes:

• If a token is configured, clients must present the same token.
• New clients receive the recent in-memory channel history.
• Channel deletion is supported by the chat protocol and client.
• The built-in server is a lightweight LAN gateway, not a hardened public chat service.