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>
79 lines
2.2 KiB
Markdown
79 lines
2.2 KiB
Markdown
# Quick Start: Authenticated Kosmi Access
|
|
|
|
## Step 1: Create Bot Account
|
|
|
|
1. Go to https://app.kosmi.io
|
|
2. Sign up with a dedicated email (e.g., `your-bot@example.com`)
|
|
3. Choose a display name (e.g., "HSO Relay Bot")
|
|
4. Save the credentials securely
|
|
|
|
## Step 2: Configure Matterbridge
|
|
|
|
Edit `matterbridge.toml`:
|
|
|
|
```toml
|
|
[kosmi.hyperspaceout]
|
|
RoomURL="https://app.kosmi.io/room/@yourroom"
|
|
Email="your-bot@example.com"
|
|
Password="your-secure-password"
|
|
```
|
|
|
|
## Step 3: Run and Verify
|
|
|
|
```bash
|
|
./matterbridge -conf matterbridge.toml
|
|
```
|
|
|
|
Watch the logs for:
|
|
- `"Authenticating with email/password..."` -- browser login starting
|
|
- `"✅ Authentication successful"` -- login completed
|
|
- `"💾 Token cached"` -- token saved for reuse
|
|
- `"Successfully connected to Kosmi"` -- connected to room
|
|
|
|
On subsequent runs with a cached token:
|
|
- `"✅ Using cached token"` -- no browser needed
|
|
|
|
## Step 4: Test
|
|
|
|
1. Send a message in the Kosmi room from a browser
|
|
2. Verify it appears in your IRC channel
|
|
3. Send a message from IRC
|
|
4. Verify it appears in Kosmi with the bot's display name
|
|
|
|
## Verification Checklist
|
|
|
|
- [ ] Bot account created at app.kosmi.io
|
|
- [ ] Credentials added to `matterbridge.toml`
|
|
- [ ] Bridge logs show authenticated connection
|
|
- [ ] Bot display name appears correctly in chat
|
|
- [ ] Messages relay bidirectionally
|
|
- [ ] Token cache file exists (`data/kosmi_token_cache.json` or `~/.matterbridge/kosmi_token_cache.json`)
|
|
|
|
## Troubleshooting
|
|
|
|
### Anonymous connection despite credentials
|
|
|
|
Check that both `Email` and `Password` are set and non-empty:
|
|
```bash
|
|
grep -E "Email|Password" matterbridge.toml
|
|
```
|
|
|
|
### Authentication fails
|
|
|
|
- Verify Chrome/Chromium is installed
|
|
- Test credentials by logging in manually at app.kosmi.io
|
|
- Delete cached token to force fresh auth: `rm data/kosmi_token_cache.json`
|
|
- Enable debug logging: `-debug`
|
|
|
|
### Token expired
|
|
|
|
The bridge automatically refreshes tokens expiring within 7 days. If refresh fails:
|
|
- Check logs for authentication errors
|
|
- Verify credentials are still valid
|
|
- Delete the token cache and restart
|
|
|
|
## Next Steps
|
|
|
|
- See [BROWSER_AUTH_GUIDE.md](BROWSER_AUTH_GUIDE.md) for full authentication details
|
|
- See [TOKEN_PERSISTENCE.md](TOKEN_PERSISTENCE.md) for token caching behavior
|