Ergo IRC Guide

Part 1: Setting the Scene

Step 1: Downloading your Daemon

1. Go to: https://github.com/ergochat/ergo/releases/latest
   Under "Assets", download the Windows build. It will be named something like: ergo-2.17.0-windows-x86_64.zip
2. Extract the ZIP into your folder of choice.
3. Ergo ships with a default config called default.yaml. A YAML file is an easy-to-read configuration format used in various programs. You need to copy this YAML file and name it ircd.yaml. Leave the default.yaml alone, it's there as a guide in case you get stuck with the formatting. YAML files can be quite picky; even one mis-spacing is enough to throw things off.
4. Enter Windows Powershell to generate your TLS certificates. Your server needs valid certificates to run, but especially if you want to make it go online. Ergo lets you generate self-signed certificates (but from here we'll call them certs), which you'll need to do in the terminal.
5. Type this exact code into the terminal ./ergo.exe mkcerts. You should now see privkey and fullchain pop up in your Ergo folder. These are PEM files, and your main two certs. You cannot have one without the other, they must be together.

You've now created the bare bones of an IRC server. The certs you just generated will be used by the TLS listeners on ports 6667 and 6697. 6667 serves plaintext, which is usable but not recommended for private communications. For an encrypted chat, you'll want to use 6697. Now you can proceed to Part 2 to create the rest of your server. If you try to connect anything to anything right now, you won't get a peep.

Part 2: Establishing the Server

Step 1: Creating an Operator Account

1. Open PowerShell in your Ergo folder and run ./ergo.exe genpasswd.
2. It will ask you to create a password, which it will then ask you to confirm. Both entries must match, though this is complicated by the fact that terminals don't show passwords! Make sure it's strong, but not too much of a pain to type.
3. Once you've confirmed your password, you'll be given a long hash starting with $2a$. Hold onto this hash and treat it like you would any other password.
4. Open your ircd.YAML file in your plaintext editor of choice, preferably Notepad.
5. Using your program's find-tools, look for this section in the opers block of the file. The oper is named "admin" by default, and you should find a line with the words password: "PASTE_YOUR_HASH_HERE".
6. Replace PASTE_YOUR_HASH_HERE with the hash you just generated, keeping the quotes.

You now have a password for your IRC server! You can change it any time by repeating the process above.

Step 2: Changing the Listeners

1. Using the find-tool in your program, find the listeners section. In it you should find these two lines around line 43, these being "127.0.0.1:6667": and "[::1]:6667":.
2. Comment out those two lines by putting a hashtag in front of them. This symbol turns a line into a comment (which won't execute as code anymore). Make sure the spacing lines up evenly. Doing this disables the localhost-only listeners so the LAN-wide listener can accept connections from other machines on your network.
3. Check that it looks exactly like this. The third line (":6667":) should already exist in the default config — you're just making sure the two lines above it are commented out:
   # "127.0.0.1:6667":
# "[::1]:6667":
":6667":

Troubleshooting: if Ergo starts but you can only connect from the same machine, double-check the spacing in this section. YAML is whitespace sensitive and if your commented lines have different indentation than the surrounding lines, the parser may choke silently.

Step 3: Changing the Firewalls

1. Open PowerShell as Administrator, otherwise it won't let you do this step in particular.
2. Copy-paste these commands into the terminal.
   New-NetFirewallRule -DisplayName "IRC 6667" -Direction Inbound -Protocol TCP -LocalPort 6667 -Action Allow -Profile Any -Enabled True
New-NetFirewallRule -DisplayName "IRC 6697" -Direction Inbound -Protocol TCP -LocalPort 6697 -Action Allow -Profile Any -Enabled True
3. Set your Wi-Fi network to Private by running Set-NetConnectionProfile -InterfaceAlias "Wi-Fi" -NetworkCategory Private. This part is important: if Windows thinks you're on a Public network, it will block incoming connections, even with these firewall rules in place.
4. If you want to check your network's firewall profile, run Get-NetConnectionProfile.

Troubleshooting: if the firewall commands fail, make sure you opened PowerShell as Administrator (right-click → Run as Administrator). If the network profile command errors out, your adapter name may differ — run Get-NetAdapter to see the exact name and substitute it for "Wi-Fi".

Your home network should now know your server exists! If you're running a chatroom with family or roommates, you can theoretically stop here. Though you still have to test it, and you'll likely want to make it go online too!

Part 3: Testing the Server

To use an IRC server, you need a client. This guide will be using HexChat, a free and widely-used IRC client for Windows. Note that HexChat is no longer actively maintained, but it's perfectly safe and has plenty of forks. If you'd rather use a different client, the general steps are roughly the same.

Step 1: Installing HexChat

1. Download HexChat from https://hexchat.github.io and run the installer. The defaults are fine.
2. On every launch, HexChat will show a Network List. Here you'll be adding your own. Fill in a nickname at the top, then click Add to create a new network entry. Name it whatever you like, e.g. My IRC Server.
3. Click Edit on your new network.
4. Under the Servers tab, remove the placeholder entry and add your server address. Since you're only connecting locally for now, use your machine's local IP followed by the port 6697. If you don't know what your IP address is, run ipconfig in PowerShell and look for the IPv4 Address in the Wi-Fi section.
5. While you're in the client's Edit window, tick Use SSL for all the servers on this network if you're using port 6697. Since you're using a self-signed cert for now, also tick Accept invalid SSL certificates. You can untick this once you have a real cert from WinACME later.
6. Click Close to exit the Edit window.

Entering your server

1. If your server is not running, open the terminal from your Ergo folder and run it with ./ergo.exe run. If your server isn't running from a terminal, it won't let you enter.
2. You should see lines like the following appear. Keep this window open — closing it stops the server.
   now listening on :6667, tls=false ...
now listening on :6697, tls=true ...
Server running
3. In a second PowerShell window, run netstat -an | findstr 6667.
4. You should see 0.0.0.0:6667 — this means it's reachable from other computers. If you only see 127.0.0.1:6667, the YAML change didn't take effect — check Step 2 of Part 2 again.

Troubleshooting: if you see nothing at all, Ergo likely didn't start properly. Switch back to the Ergo PowerShell window and look for error messages — the most common cause is a YAML formatting mistake (wrong indentation, tabs instead of spaces).

Step 4: Connecting with HexChat

1. With Ergo running, go back to HexChat and click Connect. You'll be met with Ergo's default Message-Of-The-Day and the chat interface itself.
2. If you're curious, feel free to try out some commands! Type /join #general (or any channel name you like) in the text box and press Enter. If the channel doesn't exist yet, Ergo will create it on the spot.
3. You can join multiple channels at once, just repeat the /join command. Each channel will open as a new tab in HexChat, just like a web browser.

Your server is now working on a basic LAN connection. Anyone on your local network can connect the same way you just did. If you're only using IRC for immediate friends, family or roommates, you can theoretically stop here. However, you won't be able to connect your server to any web-based clients, which we'll be going over in Part 4.

Part 4: Getting your server online

To get your server online, you'll need a stable domain, two authentic TLS certs, several opened ports in your router and a slight addition to your YAML file. While there's a lot of moving pieces, it means you own your server fully, without relying on third party services such as VPS providers.

You may not be able to proceed with the free method if:

1. Your ISP doesn't support inbound connections. Some ISPs use CGNAT (Carrier-Grade NAT), which means multiple households share one public IP. This renders port-forwarding impossible.
2. Your ISP blocks port 80, which you'll need for generating your HTTPS certs.

Assuming you haven't had either of these issues, you can proceed onto the rest of this section without any issues.

Step 1: Setting up No-IP Dynamic DNS

This gives your server a stable hostname (e.g. yourserver.ddns.net) regardless of the changes your home IP address might experience. WinACME needs this hostname to issue a real TLS certificate, and your Web-Client (which comes later in the guide) uses to connect.

1. Go to https://www.noip.com and sign up for a free account. Once you're logged in, go to Dynamic DNS → No-IP Hostnames and create a new hostname — something like yourserver.ddns.net. Write this down and treat it like you would any other password.
2. Download the No-IP DUC (Dynamic Update Client) from https://www.noip.com/download?page=win. This is a small background app that watches your public IP address and automatically updates No-IP whenever it changes. Without it, your hostname will point to the wrong IP after a router restart.
3. Install the DUC, log in with your No-IP account credentials, and make sure your hostname is ticked. Set it to run on startup so it's always active in the background.
4. Once the DUC is running, verify everything is working by looking up your hostname at https://www.nslookup.io. The A record should match your current public IP, which you can check at https://www.whatismyip.com.

Heads up!

No-IP's free tier requires you to confirm your hostname every 30 days, or they'll delete it. Keep an eye on your inbox for their reminder emails.

Step 2: Generating Certificates with WinACME

Self-signed certs (from mkcerts) work for HexChat on your LAN, but browsers will outright refuse a WebSocket connection to a self-signed cert. To use Kiwi IRC from the internet you need a real, trusted certificate. This is where WinACME comes in. It gets you a free Let's Encrypt certificate to go with your No-IP hostname.

Before you start: make sure Ergo is not running, port 80 is forwarded on your router and opened in your firewall. Opening Port 80 is a temporary measure, as WinACME needs to answer a challenge on this port to prove you control the domain.

1. Download WinACME from https://www.win-acme.com. Extract the ZIP somewhere convenient, e.g. C:\Users\YourName\Downloads\win-acme\.
2. Open PowerShell as Administrator in the WinACME folder and run ./wacs.exe. You'll be walked through an interactive menu — here's what to pick at each step:
3. Choose Create certificate (full options), not the simple IIS option.
4. For source, pick Manual input and enter your No-IP hostname, e.g. yourserver.ddns.net.
5. For validation, pick Self-hosted (HTTP-01). WinACME will spin up a tiny temporary HTTP server on port 80 so Let's Encrypt can confirm you control the hostname.
6. Leave the private key type as the default (RSA).
7. For storage, pick PEM encoded files. This gives you separate .pem files that Ergo can read. Choose a folder to save them to, e.g. C:\Users\YourName\Downloads\Ergo\certs\.
8. Accept the defaults for any remaining prompts and proceed.
9. If everything has executed correctly, WinACME will save PEM files to your chosen folder. The exact filenames depend on your WinACME version, but you'll find a certificate chain file and a private key file. Look for files ending in -chain.pem and -key.pem.
10. Open ircd.yaml and update the cert paths in two places — the 6697 TLS listener and the 8097 WebSocket listener. Make sure both point to the same folder:
    ":6697":
  tls:
    cert: C:\Users\YourName\Downloads\Ergo\certs\yourserver.ddns.net-chain.pem
    key: C:\Users\YourName\Downloads\Ergo\certs\yourserver.ddns.net-key.pem

":8097":
  tls:
    cert: C:\Users\YourName\Downloads\Ergo\certs\yourserver.ddns.net-chain.pem
    key: C:\Users\YourName\Downloads\Ergo\certs\yourserver.ddns.net-key.pem
  websocket: true
11. Start Ergo again with ./ergo.exe run. The TLS warning in HexChat should now be gone on port 6697, and Kiwi IRC will be able to connect on port 8097.

Note on renewal: Let's Encrypt certs expire after 90 days. WinACME installs a scheduled task to auto-renew them, so you shouldn't need to do anything. If renewal fails (e.g. port 80 isn't forwarded), WinACME will send a reminder email to the address you registered with.

Step 3: Port Forwarding on your Router

For anyone outside your home network to reach your server your router needs to forward the right ports to your server.

1. Find your router's admin page. Usually this involves entering a specific IP address, though this may vary between ISPs.
2. Log in with your router's admin credentials. It should be visible on the back of the router alongside your Wi-Fi password.
3. Find your PC's local IP by running ipconfig on the laptop and looking for the IPv4 Address in the Wi-Fi section — something like 192.168.1.161. It's worth assigning this as a static IP in your router's DHCP settings (look for "DHCP reservation" or "static lease") so it never changes and breaks your forwarding rules.
4. In your router's port forwarding section (often under Advanced → Port Forwarding, or NAT → Virtual Servers), add the following rules pointing to your laptop's local IP:

Protocol	Port Mapping	Service
+:+.+:+.+:+.+:+.+:+.+:+.
TCP	6667 → 6667	Plain IRC
+:+.+:+.+:+.+:+.+:+.+:+.
TCP	6697 → 6697	TLS IRC (HexChat with SSL)
+:+.+:+.+:+.+:+.+:+.+:+.
TCP	8097 → 8097	WSS WebSocket (Kiwi IRC)
+:+.+:+.+:+.+:+.+:+.+:+.
TCP	80 → 80	HTTP (WinACME certificate verification only)

5. Save the rules. You can test that a port is reachable from outside using https://www.yougetsignal.com/tools/open-ports/ — enter your No-IP hostname and port number to confirm it's open.

Note: port 80 only needs to be forwarded while running WinACME to issue or renew your certificate. You can remove it afterwards if you prefer.

Step 4: Connecting from Kiwi IRC

Kiwi IRC is a browser-based IRC client — no installation needed. It connects to your server over WebSocket Secure (WSS) on port 8097, which is why the real TLS cert from WinACME was necessary.

1. On any device, open a browser and go to https://kiwiirc.com/nextclient/.
2. Fill in the connection screen as follows:
   Server address: yourserver.ddns.net
Port: 8097
SSL/TLS: ON
Channel: #general
Nick: YourName
3. Hit Connect. You should see the server welcome message and land in your channel. This works from any network — your phone on mobile data, a friend's house, anywhere — as long as Ergo is running at home.

Troubleshooting your online connection

• "Unable to connect" — Check that Ergo is running and port 8097 is forwarded on your router.
• "Certificate error" — The WinACME cert may have expired or the paths in ircd.yaml are wrong. Check the cert files still exist and run /rehash in your IRC client.
• "Connection closed immediately" — SSL must be ON for port 8097. Make sure it's ticked.

Congratulations, you've just set up an IRC server! Invite your friends — no, drag them kicking and screaming!

If your company is hesitant to make the switch, try Kiwi or The Lounge for a modernised IRC experience. IRC is a protocol, there's no one way to run or use it, so it's more about finding what works best for your needs.

Part 5: Managing your Server

Your server is set up and online. This final part is the reference section — all the commands and concepts you'll want once people are there with you.

NickServ: Registering your Nickname

On a fresh Ergo server, anybody can use any nickname. NickServ lets users register and protect their chosen name, so nobody else can impersonate them. This is how IRC has handled identity for decades.

1. Once connected to the server, type the following in your client, substituting your chosen password and a working email address:
   /msg NickServ REGISTER yourpassword you@example.com
2. Ergo may send a verification email depending on how ircd.yaml is configured. If email verification is disabled (it is by default), your account is registered immediately.
3. Your nickname is now claimed — if anyone else tries to use it, Ergo will prompt them to identify or change nick.

Once registered, you'll need to identify yourself each time you connect. The easiest way is SASL, which HexChat handles automatically:

1. In HexChat's Network List, open your server's Edit window.
2. In the Login method dropdown, choose SASL (username + password).
3. Enter your registered nickname as the username, and your NickServ password as the password.
4. HexChat will now authenticate automatically every time you connect. No manual /identify needed.

You can also log in manually after connecting with: /msg NickServ IDENTIFY yourpassword

Other useful NickServ commands:

Operators: Using your Admin Account

You created an operator account back in Part 2. Now here's how to actually use it. Operators (opers) have elevated powers on the server — think of it as being admin. With great power, etc.

1. Connect to your server as normal.
2. Type: /oper admin yourpassword — replacing admin with the oper name from your ircd.yaml (it's admin by default), and yourpassword with the plain-text password you set up in Part 2.
3. If it worked, you'll see a confirmation message and your mode will change to include +o. You are now an IRC operator.

Useful oper commands:

A note on security: don't stay opered in indefinitely. Log in as oper when you need to do admin work, then drop back to normal with /mode yournick -o. It's good practice.

Channels: Creating and Managing Rooms

Channels in IRC are just rooms that begin with a #. Ergo creates them on the fly the moment someone joins, and destroys them when the last person leaves — unless the channel is registered with ChanServ, which makes it persistent.

1. Join the channel you want to own: /join #yourchannel. As the first person in, you're automatically given channel operator status (marked with an @ next to your name).
2. To make the channel permanent and lock in your ownership, register it with ChanServ:
   /msg ChanServ REGISTER #yourchannel
   You'll need to be identified with NickServ for this to work.
3. The channel will now persist even when empty, and your founder status is tied to your NickServ account.

Channel modes control how a room behaves. Set them with /mode #channel +flag, remove them with -flag.

Managing users in a channel:

Useful ChanServ commands: