1. Introduction
  2. Listen
  3. Environment variables
  4. Global config settings
    1. Organization name
    2. Organization URL
    3. Admin email
    4. Default connection URL
    5. Force default connection
    6. Registration is open to public
  5. User settings
    1. Notification keywords
    2. Enable notifications
    3. Expand URL to media
    4. Theme
    5. Color scheme
    6. Password
  6. Automatic startup with systemd


Convos wants to have as little configuration as possible, since we believe that good defaults are much better for the end user. Even so, there things you can change to set up Convos to behave the way you want.


You can make convos listen to a variety of addresses:

# Listen on all IPv4 interfaces
./script/convos daemon --listen http://*:8080

# Listen on all IPv4 and IPv6 interfaces
./script/convos daemon --listen "http://[::]:8000"

# Listen on a specific IPv4 and IPv6 interface
./script/convos daemon \
  --listen "" \
  --listen "http://[::1]:8080"

# Listen on HTTPS with a default untrusted certificate
./script/convos daemon --listen https://*:4000

# Use a custom certificate and key
./script/convos daemon --listen \

# Make convos available behind a reverse proxy
CONVOS_REVERSE_PROXY=1 ./script/convos daemon \

See CONVOS_REVERSE_PROXY for more details about setting up Convos behind a reverse proxy.

Environment variables

The following settings need to be set before starting Convos. New to shell environment variables? Remember to set them before the "convos" command.

# Right
CONVOS_HOME=/var/convos ./script/convos daemon;
CONVOS_REVERSE_PROXY=1 ./script/convos daemon;

# Wrong
./script/convos daemon;
./script/convos daemon CONVOS_REVERSE_PROXY=1;

The environment variables can also be specified when you run Convos inside Docker.

Changing an environment variable require Convos to be restarted before they take effect.


Can be set to any class name that inherit from Convos::Core::Backend.

Default: Convos::Core::Backend::File


This variable decides how many seconds to wait between each user to connect to a chat server. The reason for this setting is that some servers will set a permanent ban if you "flood connect".

Default: 4


Setting this variable to a true value will print extra debug information to STDERR. Another useful debug variable is MOJO_IRC_DEBUG which gives you IRC level debug information.


These two environment variables can be used to set the default theme for the CMS pages and new users.



This variable is used by Convos::Core::Backend::File to figure out where to store settings and log files.

See the FAQ for more details.

Default: $HOME/.local/share/convos/

However if you are running Convos as a snap, then CONVOS_HOME will be SNAP_USER_COMMON.

Example: $HOME/snap/convos/common

This variable is used for invite and password recovery links, and specifies how many hours the link will be valid for. Not however that when a link is used (after a new user is registered or changed the password), then link will instantly become invalid.

Default: 24.


This variable is used when generating invite links, but also useful for Convos admins who have forgotten their password. Look at "Forgotten password and invitation links" in "Convos is more user-friendly than ever" for more details.

Default value is auto generated and available in the log output when Convos is started the first time.


This value can be used to specify where Convos should write the log messages to. This settings has no default value which makes Convos write the log to STDERR.


Set this variable to specify the max size in bytes of a file that is uploaded to Convos. See also the FAQ, in case your Convos installation runs behind a reverse proxy.

Default: 40000000 (40MB)


A list (comma separated) of Perl modules that can be loaded into the backend for optional functionality. Example

CONVOS_PLUGINS=My::Cool::Plugin,My::Upload::Override ./script/convos daemon


CONVOS_REQUEST_BASE can be used instead of CONVOS_REVERSE_PROXY and the X-Request-Base HTTP header set in your web server config.




The CONVOS_REVERSE_PROXY environment variable must be set to "1" to enable reverse proxy support. This will then allow Convos to automatically pick up the X-Forwarded-For and X-Request-Base HTTP headers set in your reverse proxy web server.

Note that setting this environment variable without a reverse proxy in front will be a security issue.


You can enable the WEBIRC extension by setting an environment variable per connection name. Example:

  1. You have a connection ID "irc-localhost". (Shown as "localhost" in the sidebar)
  2. Set the following environment variable to enable WEBIRC:


Global config settings

The global config settings are available for Convos admins from within the Convos UI.

Organization name

Can be set if you want to add a touch of your organization. It will be used on the login and on the help page, to name some.

Organization URL

Used together with "Organization name" to add a link to your organization on the login screen.

Admin email

This email can be used by users to get in touch with the Convos admin. It will be displayed on login, error and help pages.

Default connection URL

This is the default connection new users will connect to. The path part is the default channel to join. "%23convos" means "#convos".

Changing this setting will not affect users who already registered.

Force default connection

Tick this box if you want to prevent users from creating connections to other than what "Default connection URL" is set to.

Registration is open to public

Tick this box if you want users to be able to register without an invite URL. If this box is not ticked then a Convos admin must go to "Users" in the web UI and generate an invite URL.

User settings

These settings are available from the Convos UI, and are specific per user account or per browser session.

Notification keywords

Can be set to a list of words that you want to get notifications about. You will always be notified if someone mention your active nick, but you can also add "milk, bread, butter" if that are your interests.

Enable notifications

Tick this checkbox if you want to get desktop notifications.

This settings is only remembered in your current browser, since it also require a browser action.

Expand URL to media

Tick this checkbox if you want images, videos and other previews inside the chat. Unticking this will require you to click on the posted link to understand what is on that page.

This settings is only remembered in your current browser.


Choose a theme for your chat. You can also create your own themes. Look at "Theming support in Convos 4.00" or "Create your own theme in minutes!" for more details.

This setting is only remembered inside the current browser. This is considered a feature, since you might want one theme on your cell phone and another on your desktop computer.

Color scheme

Some themes support dark and light color schemes. The default is to follow your desktop settings, but you can also force a dark/light scheme.

This settings is only remembered in your current browser.


Use this to change your login password. Keeping the field empty will not change your password.

Automatic startup with systemd

Here is an example systemd file, that can be placed in /etc/systemd/system/convos.service.

Note that the Environment variables should be review and changed to suit your needs.

Description=Convos service

ExecStart=/path/to/convos/script/convos daemon --listen http://*:8081


After creating the file, you can run the following commands to start the service:

systemctl daemon-reload
systemctl enable convos.service
systemctl start convos.service
systemctl status convos.service

Running Convos under systemd without a custom CONVOS_LOG_FILE will send all the log messages to syslog, which normally logs to /var/log/syslog.