Guides

Set up background notifications, connect through CLoak, or route a network through a proxy. For a first direct IRC or soju connection, begin with Getting started.

Push notifications

motd uses UnifiedPush for Google-free push delivery. ntfy can act as the distributor, but your soju bouncer must advertise soju.im/webpush. A plain IRC server cannot provide this push delivery.

Set up ntfy

1. Install ntfy from F-Droid. This build contains no Firebase and maintains its own instant-delivery connection. Grant notification permission, allow background operation, and open ntfy once.
2. Connect motd to your soju bouncer at least once so it can detect Web Push support.
3. Open Settings → Message delivery in motd and select UnifiedPush.
4. If Android asks for a distributor, choose ntfy. motd selects it automatically when it is the only installed distributor.
5. Leave motd open until the status card says UnifiedPush active. It first obtains an endpoint, then waits for soju to confirm that an encrypted test delivery succeeded.
6. Background motd and send a direct message to your nick from another IRC client. Confirm that the notification arrives before relying on background push.

You do not need an ntfy topic or account when using the public https://ntfy.sh server. motd creates and manages its private push endpoints. soju encrypts the payload and motd decrypts it on your device; ntfy cannot read the IRC message.

Verification and socket fallback

motd closes a network's IRC socket only after soju acknowledges its current endpoint. Networks without Web Push support, or whose registration has failed, remain connected through the foreground service. The delivery setting stays on UnifiedPush and the status card reports socket fallback rather than silently changing modes.

soju sends Web Push for direct messages and channel highlights. Ordinary channel messages are fetched through CHATHISTORY when motd returns to the foreground. Foregrounding reconnects first, runs catch-up, and keeps the socket available while you use the app.

The status card distinguishes endpoint setup, server verification, active delivery, partial socket fallback, and errors. Retry runs endpoint registration again without discarding your delivery-mode choice.

Use a self-hosted ntfy server

1. In ntfy, open Settings and change the default server to your HTTPS ntfy URL.
2. If authentication is required, add credentials under Manage users.
3. Return to motd and select UnifiedPush again to obtain endpoints from that server.

The phone must be able to maintain a connection to the server. Use a valid HTTPS certificate where possible; current ntfy Android releases also support self-signed and client certificates. See the ntfy phone documentation and UnifiedPush ntfy guide for server-specific configuration.

The public ntfy service has its own usage policy and availability. Self-hosting is optional and gives you control over retention, accounts, and service reliability.

Keep background delivery working

• Allow notification permission for both ntfy and motd.
• Exempt ntfy from battery optimization on devices that aggressively stop background apps.
• Allow ntfy background data and automatic startup when those controls exist.
• Do not force-stop ntfy: Android prevents force-stopped apps from receiving messages.

The battery exemption shown in motd primarily protects persistent IRC connections. In UnifiedPush mode, ntfy is the app that must remain reachable in the background.

Troubleshoot push delivery

• UnifiedPush is disabled: connect to soju first and confirm that the bouncer advertises soju.im/webpush.
• No distributor is installed: open ntfy, confirm UnifiedPush is enabled in its settings, then restart motd or select UnifiedPush again.
• No notification arrives: confirm ntfy reports an active connection, then check Android's battery, background-data, and notification permissions.
• Endpoint verification fails, or messages appear only after opening motd: inspect the status card and use Retry for endpoint or verification failures. Affected networks remain socket-backed until verification succeeds.
• Delivery stopped after a force-stop: reopen ntfy. Android intentionally blocks delivery to force-stopped apps.
• Multiple distributors are installed: use Choose distributor or Change distributor in the status card. motd does not silently make an ambiguous choice; changing distributor cleans up the previous instances before requesting replacements.
• Self-hosted delivery fails: check the ntfy URL, TLS certificate, login, reverse proxy WebSocket/streaming support, and whether the phone can reach the server outside Wi-Fi.

Read the full motd ntfy guide for delivery details.

CLoak

motd connects to CLoak as a standard IRC network. Compatibility and the limitations below are documented for CLoak v0.4.0, including live messages and buffered playback after reconnecting.

Configure CLoak first

Set up a CLoak user, at least one upstream network, and an IRC listener reachable from your phone. Follow the upstream CLoak configuration documentation for listener, user, and network settings.

Use TLS for any connection that leaves the bouncer host. The listener's certificate must be valid for the hostname you enter in motd.

Add an IRC network

Choose IRC network, not the guided bouncer option, and enter:

• Host and port: CLoak's IRC listener address and port.
• TLS: on for a normal remote connection.
• Nick and username: the identity motd should present to CLoak. These fields do not select the CLoak account or upstream network.
• Server password: username/network:password, using your CLoak account, configured network name, and password.
• SASL: None. CLoak v0.4.0 uses IRC PASS for downstream authentication, not SASL.

Create one motd entry per upstream CLoak network. Change the network segment of the server password for each entry; network names and their case must match CLoak's configuration exactly.

History and capability limits

CLoak v0.4.0 and motd negotiate batch, message-tags, and server-time. CLoak keeps the upstream IRC connection alive and automatically replays buffered messages when motd reconnects. No manual history request is needed.

CLoak v0.4.0 does not advertise downstream SASL, draft/chathistory, draft/read-marker, soju.im/bouncer-networks, or soju.im/webpush. Replay is supplied by CLoak rather than motd's infinite-scrollback protocol. Each network needs its own motd entry, and cross-device read-marker sync and bouncer Web Push are unavailable.

Troubleshoot CLoak

• Password rejected or numeric 464: check the full username/network:password value. Put it in Server password, not the SASL password field.
• Only one network works: check the other network's exact name and case in CLoak's configuration, then create a separate motd entry.
• TLS fails: use the certificate's hostname, confirm the phone trusts its issuer, and check that the port is CLoak's IRC listener, not its web interface.
• Old messages are not replayed: enable and configure CLoak's buffering modules. Playback comes from CLoak rather than a CHATHISTORY request.

See the full motd CLoak guide for the documented connection and compatibility details.

SOCKS5, Tor & VLESS

Obfuscation is configured per network, for either an IRC server or a soju bouncer. It can help where ordinary IRC/TLS is blocked or conspicuous, but it is not an anonymity guarantee and may have legal or policy implications where you live.

Choose a transport

• Off: connect directly.
• SOCKS5: use an existing proxy and enter its host and port. DNS is resolved through the proxy.
• Tor (Orbot): install Orbot and start it before choosing this option. motd uses Orbot's local SOCKS5 proxy, normally with a .onion bouncer address. A hidden-service address avoids exposing the bouncer's public IP.
• VLESS + REALITY: motd runs an embedded sing-box client and automatically exposes a local SOCKS proxy. Supply an existing VLESS URI; no companion Android proxy app is needed.

The embedded VLESS transport requires an arm64-v8a Android device. See the installation requirements.

Configure VLESS + REALITY

1. Add or edit the network. Its Host, Port, and TLS fields describe the IRC server or bouncer destination after the tunnel, not the public VLESS ingress. The VLESS URI contains the public ingress address.
2. Open Settings → Networks → your network → Connection / Obfuscation.
3. Choose VLESS + REALITY (sing-box), paste your existing URI, and save.
4. Reconnect. On first use of a self-signed or loopback certificate, verify its fingerprint before accepting motd's certificate-trust prompt. motd pins that leaf certificate for later connections.

Docker loopback warning: when the proxy and bouncer run in separate containers on a shared Docker network, use the bouncer's Docker DNS name, such as host soju, port 6697, with TLS enabled. Do not use 127.0.0.1: it points back to the proxy container. Loopback is correct only when the proxy and bouncer share a network namespace.

If the bouncer is elsewhere, keep its normal hostname and port and adjust the Xray route restriction accordingly. For VLESS networks, motd also accepts a Soju file host at the exact user-configured VLESS ingress hostname, while refusing unrelated hosts before sending the network credential. HTTPS certificate validation is still required.

Troubleshoot the tunnel

• Cannot reach the ingress: check that the VPS firewall allows the selected TCP port and that Xray validates its configuration.
• REALITY negotiation fails: confirm that the REALITY server name is reachable from the VPS and supports TLS 1.3.
• The bouncer certificate changed: review the new certificate prompt and verify the fingerprint before trusting the replacement.
• The embedded transport is unavailable: confirm the device is arm64-v8a; the embedded option requires that architecture.

The full obfuscation guide includes VPS/Xray setup and routing details. Use that guide to configure the server rather than putting the VLESS ingress into motd's destination Host and Port fields.