LiveKit Service Implementation Summary

LiveKit Service Implementation Summary

Overview

This document summarizes the implementation of LiveKit as a managed service in Voice Mode, created during the night session of 2025-08-12.

What Was Implemented

1. Core Service Files

Installation (voice_mode/tools/services/livekit/install.py)

• Platform detection (macOS uses Homebrew, Linux uses official script or direct download)
• Binary installation with version management
• Configuration file generation (dev mode with devkey/secret)
• Service file installation
• Auto-enable option for startup

Uninstallation (voice_mode/tools/services/livekit/uninstall.py)

• Service stopping and disabling
• Binary and configuration removal
• Optional complete data cleanup
• Homebrew detection and warning

Helper Functions (voice_mode/utils/services/livekit_helpers.py)

• find_livekit_server() - Locate LiveKit binary
• find_livekit_config() - Locate configuration file
• check_livekit_health() - Health check via HTTP
• get_livekit_version() - Version detection
• is_livekit_installed() - Installation check

2. Service Templates

systemd (voice_mode/templates/systemd/voicemode-livekit.service)

• Proper service configuration
• Health check on startup
• Resource limits (1GB memory, 50% CPU)
• Environment variables for dev credentials
• Journal logging

launchd (voice_mode/templates/launchd/com.voicemode.livekit.plist)

• macOS service configuration
• Auto-start at login
• Log file paths
• Environment setup including PATH

3. Configuration Updates

voice_mode/config.py

Added LiveKit configuration constants:

• LIVEKIT_PORT (default: 7880)
• LIVEKIT_URL (default: ws://localhost:7880)
• LIVEKIT_API_KEY (default: devkey)
• LIVEKIT_API_SECRET (default: secret)

4. Service Management Integration

voice_mode/tools/service.py

Extended to support LiveKit:

• Added LiveKit to service name literals
• Updated get_service_config_vars() for LiveKit
• Modified all port selection logic to include LiveKit
• Updated docstrings

5. CLI Commands

voice_mode/cli.py

Added complete LiveKit command set:

• voice-mode livekit install - Install LiveKit server
• voice-mode livekit uninstall - Remove LiveKit
• voice-mode livekit start/stop/restart - Service control
• voice-mode livekit enable/disable - Startup management
• voice-mode livekit status - Check service status
• voice-mode livekit logs - View service logs
• voice-mode livekit update - Update service files

Key Design Decisions

1. Dev Mode by Default

Following Mike's guidance, the implementation uses LiveKit's dev mode with standard credentials (devkey/secret) for easy setup.

2. Platform-Specific Installation

• macOS: Prefers Homebrew if available
• Linux: Uses official install script, falls back to direct binary download
• Both: Install to ~/.voicemode/services/livekit/ for consistency

3. Service Pattern Consistency

LiveKit follows the same patterns as Whisper and Kokoro:

• Same directory structure
• Same service management commands
• Same configuration approach
• Same health check pattern

4. Configuration File

Creates a YAML configuration file with:

• Dev mode keys
• Port configuration
• RTC port range
• Logging settings
• Room auto-creation

What's Still Needed

1. MCP Tool Registration

The install_livekit and livekit_status tools need to be registered in the MCP server.

2. Provider Discovery

LiveKit should be added to the provider discovery system so it's automatically detected when running.

3. Web Interface

The web interface in docs/web/ needs to be updated to:

• Auto-detect local LiveKit server
• Configure connection settings
• Handle fallback to cloud

4. Documentation

• Update main README with LiveKit information
• Create user guide for LiveKit setup
• Update configuration documentation

5. Testing

• Test installation on both macOS and Linux
• Verify service management works correctly
• Test web interface connection
• Verify TailScale access

Usage Examples

Installing LiveKit

# Basic installation
voice-mode livekit install

# Custom port
voice-mode livekit install --port 8880

# Force reinstall
voice-mode livekit install --force

# Install and enable at startup
voice-mode livekit install --auto-enable

Managing the Service

# Check status
voice-mode livekit status

# Start/stop
voice-mode livekit start
voice-mode livekit stop

# View logs
voice-mode livekit logs --lines 100

# Enable at startup
voice-mode livekit enable

Uninstalling

# Basic uninstall
voice-mode livekit uninstall

# Remove everything
voice-mode livekit uninstall --remove-all-data

Next Steps

1. Complete MCP tool registration
2. Add provider discovery support
3. Update web interface for LiveKit connection
4. Test the complete workflow
5. Create user documentation
6. Submit PR for review

Notes

This implementation follows the existing patterns in Voice Mode closely, making it feel like a natural extension rather than a bolt-on feature. The dev mode configuration makes it extremely easy to get started, which aligns with Voice Mode's philosophy of minimal setup friction.