c88b75f30d
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>
131 lines
3.2 KiB
Markdown
131 lines
3.2 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
cd irc-kosmi-relay
|
|
|
|
# Download dependencies
|
|
go mod download
|
|
|
|
# Build
|
|
go build -o matterbridge .
|
|
```
|
|
|
|
## Step 2: Configure
|
|
|
|
Copy and edit the example configuration:
|
|
|
|
```bash
|
|
cp matterbridge.toml.example matterbridge.toml
|
|
nano matterbridge.toml
|
|
```
|
|
|
|
Update these values:
|
|
|
|
```toml
|
|
[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:
|
|
|
|
```toml
|
|
[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
|
|
|
|
```bash
|
|
./matterbridge -conf matterbridge.toml
|
|
```
|
|
|
|
Or with debug logging:
|
|
|
|
```bash
|
|
./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
|
|
|
|
1. **Kosmi --> IRC**: Send a message in your Kosmi room. It should appear in IRC as:
|
|
```
|
|
[kosmi] <username> your message here
|
|
```
|
|
|
|
2. **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](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](DOCKER_QUICKSTART.md) -- Deploy with Docker
|
|
- [JACKBOX_INTEGRATION.md](JACKBOX_INTEGRATION.md) -- Enable Jackbox Game Picker
|
|
- [IRC.md](../IRC.md) -- IRC commands and voting reference
|
|
- [MUTE_CONTROL.md](MUTE_CONTROL.md) -- Control Jackbox announcement muting
|