Files

docs: comprehensive documentation overhaul

Rewrite README.md and all setup guides to reflect the current native
GraphQL WebSocket architecture (replacing stale headless Chrome/WebSocket
interception descriptions). Add new docs/IRC.md with complete IRC command
reference, vote syntax, and ticker symbol table.

Archive pre-edit docs to docs/archive/setup-backup-2026-05-10/ and move
historical development notes from docs/ root into docs/archive/.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-05-12 22:01:25 -04:00

3.2 KiB

Raw Blame History

Quick Start Guide

Get the Kosmi-IRC bridge running in minutes.

Prerequisites

Go 1.23 or higher
Chrome/Chromium (only needed for email/password authentication)
A Kosmi room URL
(Optional) IRC server access for full relay

Step 1: Build the Bridge

cd irc-kosmi-relay

# Download dependencies
go mod download

# Build
go build -o matterbridge .

Step 2: Configure

Copy and edit the example configuration:

cp matterbridge.toml.example matterbridge.toml
nano matterbridge.toml

Update these values:

[kosmi.hyperspaceout]
RoomURL="https://app.kosmi.io/room/@YOUR_ROOM"

[irc.zeronode]
Server="irc.libera.chat:6697"
Nick="your-bot-nick"
UseTLS=true

[[gateway.inout]]
account="irc.zeronode"
channel="#your-channel"

Important: The Kosmi channel is always "main" (one channel per room). The IRC channel must include #.

Optional: Authenticated Kosmi Access

To use a Kosmi account instead of anonymous access, add credentials:

[kosmi.hyperspaceout]
RoomURL="https://app.kosmi.io/room/@YOUR_ROOM"
Email="your-email@example.com"
Password="your-password"

This requires Chrome/Chromium for the initial browser-based login. The JWT is cached locally for subsequent runs.

Step 3: Run

./matterbridge -conf matterbridge.toml

Or with debug logging:

./matterbridge -conf matterbridge.toml -debug

Expected Output (Success)

INFO Running version ...
INFO Connecting to Kosmi
INFO Extracted room ID: @YOUR_ROOM
INFO No credentials provided, using anonymous access
INFO Successfully connected to Kosmi
INFO Connection succeeded (IRC)
INFO Gateway(s) started successfully. Now relaying messages

Step 4: Test the Relay

Kosmi --> IRC: Send a message in your Kosmi room. It should appear in IRC as:
```
[kosmi] <username> your message here
```
IRC --> Kosmi: Send a message in your IRC channel. It should appear in Kosmi as:
```
[irc] <username> your message here
```

Troubleshooting

Kosmi connection fails

Verify the room URL is correct (use the full URL from your browser)
Check network connectivity: curl -I https://app.kosmi.io
Run with -debug for detailed WebSocket connection logs

Supported room URL formats:

https://app.kosmi.io/room/@roomname
https://app.kosmi.io/room/roomid

Authentication issues

Verify Chrome/Chromium is installed: which chromium chromium-browser google-chrome
Check credentials are correct by logging in manually at app.kosmi.io
Delete the token cache to force a fresh login: rm -f data/kosmi_token_cache.json
See BROWSER_AUTH_GUIDE.md for detailed auth troubleshooting

Messages not relaying

Confirm both bridges are connected (look for success messages in logs)
Verify channel names match in the gateway configuration
Enable debug logging to trace message flow

Next Steps

DOCKER_QUICKSTART.md -- Deploy with Docker
JACKBOX_INTEGRATION.md -- Enable Jackbox Game Picker
IRC.md -- IRC commands and voting reference
MUTE_CONTROL.md -- Control Jackbox announcement muting

3.2 KiB Raw Blame History