IRC-kosmi-relay/docs/setup/QUICKSTART.md

# 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