Skip to content

Quickstart Guide

Francesco edited this page Oct 20, 2020 · 20 revisions

Weechat-Android is a relay client, that is it's not a standalone client, but one that connects to your copy of WeeChat running on your server. You can connect the two in a number of ways, listed below.


  • A server that has open ports, or is running SSH or HTTP service
  • WeeChat 0.3.8 or newer
  • Android 4 (api 16) or newer

Plain connection

Configure WeeChat

Since this relies on the relay plugin built into weechat, we need to configure it first. Type /help relay to see the help on the relay plugin. The simplest way to connect Weechat-Android and WeeChat is to add an insecure plain-text relay:

/relay add weechat 8001
relay: listening on port 8001 (relay: weechat, max 5 clients)
relay: relay "weechat" (port 8001) added

Note that it says “relay: weechat”, which we need; another option is to use the “irc” protocol that makes the relay act like an IRC bouncer. We can't use the latter.

Weechat-Android also currently requires a password to be set. Set it with

/set "your-secret-password"

Note that since WeeChat is now listening for connections on port 8001, you need to make sure your firewall is setup to allow that port. If you are behind a router, you will need to configure port forwarding.

Configure Weechat-Android

Refer to the Readme for installation instructions. After installing, navigate to SettingsConnection and set the Connection type to Plain connection. You must set:

  • Relay host — to the ip address/hostname of the machine where WeeChat is running
  • Relay port — to the port WeeChat is listening on, if you're following along it should be 8001.
  • Relay password — to "your-secret-password".

When you are done, close the settings and tap on the sad kitty. If everything was configured successfully, you should be looking at a list of all the buffers you have open in WeeChat.

Other connections


WeeChat can automatically detect WebSocket traffic, so the setup is the same as for the Plain connection.


The setup is mostly the same as the plain connection, the idea being that the endpoints are the same, but your connection goes through your SSH proxy. Simply set your Connection type to SSH tunnel, and set the settings in the appropriate menu. Refer to Setting up SSH for details.

SSL & WebSocket SSL

You will need to do /relay add ssl.weechat 9001 and point WeeChat at your certificates. Refer to Using SSL with WeeChat for details. You can use self-signed certificates, but we are still verifying them; also, Android has certain requirements for certificates as well. Please make sure you follow the instructions.

Useful notes

  • Type /fset relay to see all relay options. One particularly interesting option is relay.weechat.commands, which can prevent relay from running certain commands.

  • /relay without parameters can be useful to see current relay connections.

  • /relay raw will show you the traffic that's going through relay, which is very useful for debugging.