Soju Documentation

Soju has its own user documentation, separate from these documents. Some pointers:

• BouncerServ documentation
• Client configuration guide

TODO, but at least:

• Gamja
• Goguma
• Halloy (Setup guide)
  • Make sure you have version 2025.9 or later — important
• Senpai (Setup guide)
• Weechat (Setup guide)
  • TODO: recommended config; at least soju.py
• Weechat-Android (Setup guide)

Let me know if you have an iOS client you like / that I should recommend.

TODO, for now see generic

[buffer.channel.topic_banner]
enabled = true
max_lines = 2

[buffer.chathistory]
infinite_scroll = true

[buffer.internal_messages]
success.smart = 300
error.smart = 300

[buffer.server_messages]
change_nick.smart = 900
join.smart = 900
part.smart = 900
quit.smart = 900
topic.enabled = false

[notifications]
direct_message.show_toast = true
file_transfer_request.show_toast = true
highlight.show_toast = true

[servers.soju]
server = "chat.remexre.com"
port = 6666
chathistory = true

[servers.soju.sasl.plain]
username = "..."
password_command = "..."

TODO, for now see generic

address chat.remexre.com:6666
username ...
password-cmd ...

on-highlight-beep true

TODO, for now see generic

Weechat-Android setup

Even more TODO

These steps are intended to apply to clients that don’t have a specific setup guide. They also describe the configuration being applied by the other guides in more detail.

Background about IRC

TODO:

• Bouncers and servers and networks, oh my
• Accounts
• *Serv
• Culture
• Some channels to join

Getting an account

Just ask me for an account, with your preferred username. I’ll send you back a temporary password, which you’ll change in the next step.

This username and password only apply to the bouncer; they don’t apply to any other network/server, not even mine.

Connecting to the bouncer for the first time

You can connect to Soju with the following connection details (pretending that your username is myusername and your temporary password is mypassword):

• Host: chat.remexre.com
• Port: 6666
• TLS: true
  • This may be the default in your client.
• Authentication: SASL PLAIN
  • This may be the default in your client.
• Username: myusername
  • If your client doesn’t support the chathistory IRCv3 extension, you should use myusername@myhostname instead. It’s not required that myhostname matches your hostname, it just has to be unique per-client so that Soju can keep track of what messages the client has seen.
• Password: mypassword
  • If your client supports a “password command” feature, you should use it for your actual password. Password managers such as pass and 1Password can be integrated with this feature.
  • For this temporary password, though, it’s fine to put it into the config file as plain text.

After configuring your client with these settings, connect to the server.

Once the connection succeeds, you probably won’t see much, since you won’t be connected to any networks. Before connecting to any networks, though, change your password.

If your client has a UI option to change your password, see if that works. If not, you can change it by messaging BouncerServ.

BouncerServ is a bot on the Soju server that you can message to administer your account. It accepts a simplified Unix-like command syntax. Some of its features can be provided by clients in other ways, but it’s the least common denominator.

To open DMs with BouncerServ, either click the appropriate “message user” button in your client’s UI, or run /query BouncerServ.

To change your password, send a message like user update -password mynewpassword.

Once you’ve changed it, disconnect, put your new password into your config, and reconnect.

Connecting to a network

This is another task that your client might have a special UI for doing when connected to Soju.

Make sure you are going through Soju though, not adding another network to your client — otherwise, you probably won’t have history saved, and won’t be able to connect from multiple devices at once. If in doubt, use the BouncerServ instructions.

Since Soju is connecting to the network on your behalf, this is another feature that can be accessed through BouncerServ.

First, you need to find the connection parameters for the network. Usually, all you need is the hostname, since most modern networks are on port 6697, use TLS, and don’t require authentication to connect.

A few networks are:

• Libera.Chat: libera.chat
• OFTC: irc.oftc.net
• My server: chat.remexre.com

To configure Soju to connect to the network, send BouncerServ a message like network create -addr chat.remexre.com.

If the network does require additional configuration, you can pass additional arguments. Send help network create to see the available options.

If you need to change the network’s settings after you connect, you can use the network update command. If you didn’t use -name when you ran network create, use the hostname.

If your client supports the soju.im/bouncer-networks IRCv3 extension, it should automatically connect to the network. This should include at least Gamja, Goguma, Halloy (version 2025.9 and later), Senpai, and Weechat with the soju.py plugin.

If not, you’ll have to add a new connection from your client to the bouncer. Add a suffix like myusername/libera.chat to your username to let the bouncer know what network the connection represents. You should still have one unsuffixed connection to the bouncer to be able to message BouncerServ as well.

Creating an account on a network

TODO, optional

Joining a channel

Once you’ve connected to a network, you probably want to join a channel. This can be done with the /join command.

For example, on my server, the #general channel is the most active. Run the command /join #general on the buffer/pane for that network to join it.

DMing a user

TODO /query othernick