Halloy setup guide: config, servers, and the keybindings that matter

Halloy is fast to install and fast to get wrong-looking if you stop at the defaults. This is the full setup: install, one server with SASL, more than one server, bouncer integration, and the config.toml options that make it feel like your client instead of the demo.

1. Install #

• Windows: winget install squidowl.halloy
• macOS: brew install --cask halloy
• Linux: Flathub
• Everything else: halloy.chat

Halloy reads its configuration from a single config.toml file — no database, no hidden state. On first run it creates one with Libera.Chat already configured; on Linux it lives at ~/.var/app/org.squidowl.halloy/config/halloy/config.toml (Flatpak) or ~/.config/halloy/config.toml, on macOS at ~/Library/Application Support/halloy/config.toml, and on Windows at %APPDATA%\halloy\config.toml.

2. One server, with SASL #

Replace the default server block with your own, using a registered nickname:

[servers.liberachat]
nickname = "yournick"
nick_password = ""
server = "irc.libera.chat"
port = 6697
use_tls = true
channels = ["#yourchannel"]

[servers.liberachat.sasl.plain]
username = "youraccount"
password = "yourpassword"

Restart Halloy (or reload config from the command bar) and you connect, authenticate, and join automatically. use_tls = true on port 6697 is not optional — see the protocol page for why plaintext IRC on 6667 is a bad default in 2026.

3. More than one network #

Each [servers.name] block is independent — add as many as you use:

[servers.liberachat]
nickname = "yournick"
server = "irc.libera.chat"
port = 6697
use_tls = true
channels = ["#yourchannel"]

[servers.rizon]
nickname = "yournick"
server = "irc.rizon.net"
port = 6697
use_tls = true
channels = ["#help"]

They appear as separate entries in the sidebar; switching between them is Alt+↑/↓ or a click, no reconnect involved.

4. Pairing with a bouncer #

Halloy has no built-in bouncer, but its IRCv3 support (SASL, chathistory, server-time) means it plays cleanly with one. Point a server block at your soju instance instead of a network directly:

[servers.soju]
nickname = "yournick"
server = "your-soju-host"
port = 6697
use_tls = true

[servers.soju.sasl.plain]
username = "yournick/liberachat"
password = "yourbouncerpassword"

With that in place you get real scrollback on reconnect — the thing plain IRC cannot do on its own. The same pattern works against ZNC, though replay will look like timestamped history lines rather than native chathistory.

5. Config worth knowing about #

Beyond servers, config.toml covers the rest of the client. A few sections people actually change:

[buffer]
nickname.color = "unique"
timestamp.format = "%R"

[notifications]
show = true
sound = true

[keyboard]

• Themes ship built in and switch from the command bar (/theme) or a [appearance] block if you want to pin one.
• Notifications are on by default; the block above is where you'd mute sound and keep desktop popups, or vice versa.
• The full option list is documented at halloy.chat and is exhaustive — treat the above as a starting point, not the ceiling.

6. Keybindings that matter #

Halloy is pane-based rather than tab-based, which changes the muscle memory if you're coming from a client like WeeChat:

• Alt+↑ / Alt+↓ — move between buffers
• Alt+number — jump to a specific buffer
• Ctrl+K — command palette (fuzzy search everything)
• Drag a buffer's tab to split the window into panes — this is Halloy's signature move, and worth trying deliberately once rather than discovering by accident

If something looks wrong #

A blank or unstyled window on first launch usually means the config file has a syntax error — TOML is whitespace-sensitive about table headers. Halloy will fall back to defaults rather than crash, so check the file directly if your servers aren't showing up as expected.

From here, the basics are the same as anywhere else on IRC: commands cheat sheet.