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

2.2 KiB

Raw Blame History

Quick Start: Authenticated Kosmi Access

Step 1: Create Bot Account

Go to https://app.kosmi.io
Sign up with a dedicated email (e.g., your-bot@example.com)
Choose a display name (e.g., "HSO Relay Bot")
Save the credentials securely

Step 2: Configure Matterbridge

Edit matterbridge.toml:

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

Step 3: Run and Verify

./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

Send a message in the Kosmi room from a browser
Verify it appears in your IRC channel
Send a message from IRC
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:

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 for full authentication details
See TOKEN_PERSISTENCE.md for token caching behavior

2.2 KiB Raw Blame History