ops-jrz1/docs/worklogs/2026-01-20-musiclink-bot-integration.org

MusicLink Bot Integration and Matterbridge Matrix Pivot

• Session Summary
  • Date: 2026-01-20
  • Focus Area: Integration of MusicLink bot into ops-jrz1 infrastructure
• Accomplishments
• Key Decisions
  • Decision 1: Pivot to Matrix-mediated bridging
  • Decision 2: Read-only listener for Slack-bridged rooms
  • Decision 3: Use local file path for Flake input (Workaround)
• Problems & Solutions
• Technical Details
  • Code Changes
  • Commands Used
• Process and Workflow
• Next Steps

Session Summary

Date: 2026-01-20

Focus Area: Integration of MusicLink bot into ops-jrz1 infrastructure

Accomplishments

• Analyzed and cloned musiclink source code from ops-jrz1 to local dev environment.
• Integrated musiclink as a Nix Flake input in flake.nix.
• Created modules/musiclink.nix to manage systemd services for the bot and its Matterbridge adapter.
• Extended services.dev-platform in modules/dev-services.nix to include MusicLink configuration.
• Migrated Slack tokens to sops-nix and added new musiclink-matrix-token.
• Provisioned @musiclink:clarun.xyz user on the homeserver via Matrix API.
• Successfully deployed the configuration to ops-jrz1 VPS.
• Verified VM integration tests pass with the new module.
• Granted server admin privileges to @musiclink:clarun.xyz to facilitate room management.

Key Decisions

Decision 1: Pivot to Matrix-mediated bridging

• Context: musiclink requires Matterbridge WebSocket API. Matterbridge (stable) lacks Slack Socket Mode support, which our Slack App requires.

• Options considered:

  1. Patch Matterbridge to support Socket Mode (high effort).
  2. Use Slack Events API (requires public ingress/TLS management).
  3. Route via Matrix using mautrix-slack as the gateway (Matrix-native approach).
• Rationale: Matrix-mediated routing leverages existing infrastructure (mautrix-slack) and treats Matrix as the universal communication bus.
• Impact: MusicLink -> Matterbridge -> Matrix -> mautrix-slack -> Slack.

Decision 2: Read-only listener for Slack-bridged rooms

• Context: Safety constraint to prevent the bot from posting test/automated messages back to Slack during initial setup.
• Rationale: Configured Matterbridge gateway as [[gateway.in]] for the Matrix side.
• Impact: The bot can see and process links from Slack but cannot post back to the channel.

Decision 3: Use local file path for Flake input (Workaround)

• Context: nix flake check failed to authenticate with git.clarun.xyz via HTTPS/SSH.
• Rationale: Cloned the repo locally and used git+file:///home/dan/proj/musiclink to unblock development.
• Impact: Filed beads issue ops-jrz1-zr0q to resolve permanent git access.

Problems & Solutions

Problem	Solution	Learning
Matterbridge failed with not_allowed_token_type on Slack	Pivoted to Matrix bridge; Matterbridge RTM is incompatible with modern Socket Mode apps	Matterbridge Slack support is lagging behind Slack API changes
MusicLink crashed with "malformed ws URL"	Changed protocol from http:// to ws:// in bot config	WebSocket clients are strict about the ws:// scheme
Matterbridge failed Matrix login with missing field password	Added MxID to config to trigger token-based auth bypass	Matterbridge needs explicit User ID to use an existing access token
M_FORBIDDEN when joining portal room	Granted server admin to bot via conduwuit --execute command	Admin status alone doesn't bypass invite-only rules for standard /join calls

Technical Details

Code Changes

• modules/musiclink.nix: Defines systemd services with DynamicUser and LoadCredential for secret safety.
• hosts/ops-jrz1.nix: Enabled MusicLink, disabled Maubot, added sops secrets.
• flake.nix: Wired up the new input and passed it to configurations and tests.

Commands Used

# Register Matrix user
curl -s -X POST -H "Content-Type: application/json" \
  -d '{"username":"musiclink", "password":"...", "auth":{"type":"m.login.registration_token", "token":"..."}}'
  http://127.0.0.1:8008/_matrix/client/v3/register

# Grant admin status via Conduwuit console
conduwuit -c continuwuity.toml --execute "admin users make-user-admin @musiclink:clarun.xyz"

# Find Room ID from mautrix-slack DB
sudo -u postgres psql mautrix_slack -c 'SELECT id, mxid, name FROM portal;'

Process and Workflow

• Used nix flake check and VM integration tests to verify module structure before deployment.
• Incremental deployment via nixos-rebuild switch allowed catching configuration mismatches (http vs ws, MxID requirement).
• Conscious pivot from a blocked path (Matterbridge Slack) to a viable one (Matrix mediation).

Next Steps

• User to invite @musiclink:clarun.xyz to the #music Matrix room.
• Verify message flow: Slack -> Matrix -> MusicLink.
• Enable outbound posting (gateway.out) once processing logic is verified.
• Resolve git access issue for the musiclink flake input.
• Close beads task ops-jrz1-k3e0 (AGENTS.md review).