2040 Livekit Service Design D145499f

# LiveKit Service Integration Design

## Overview

This document outlines the design for integrating LiveKit as a managed service in Voice Mode, similar to how Whisper and Kokoro are currently managed.

## Architecture Overview

```
Voice Mode
├── CLI Commands
│   ├── voice-mode livekit install
│   ├── voice-mode livekit start/stop/status
│   └── voice-mode livekit uninstall
├── MCP Tools
│   ├── install_livekit()
│   ├── Extended service() tool
│   └── livekit_status()
└── Service Management
    ├── systemd/launchd templates
    ├── Health checks
    └── Auto-discovery
```

## Installation Strategy

### Binary Installation
1. **macOS**: Use `brew install livekit` (already available)
2. **Linux**: Use official install script: `curl -sSL https://get.livekit.io | bash`
3. **Fallback**: Direct binary download from GitHub releases

### Service Location
- Install to: `~/.voicemode/services/livekit/`
- Binary: `~/.voicemode/services/livekit/livekit-server`
- Config: `~/.voicemode/services/livekit/livekit.yaml`
- Logs: `~/.voicemode/logs/livekit/`

## Configuration

### Dev Mode (Default)
```yaml
# ~/.voicemode/services/livekit/livekit.yaml
port: 7880
rtc:
  port_range_start: 50000
  port_range_end: 60000
  use_external_ip: false
keys:
  devkey: secret
log_level: info
```

### Environment Variables
```bash
LIVEKIT_URL=ws://localhost:7880
LIVEKIT_API_KEY=devkey
LIVEKIT_API_SECRET=secret
```

## Service Templates

### systemd Template
```ini
[Unit]
Description=Voice Mode LiveKit Server
After=network.target

[Service]
Type=simple
ExecStart={LIVEKIT_BIN} --config {CONFIG_FILE} --dev
WorkingDirectory={WORKING_DIR}
ExecStartPost=/bin/sh -c 'while ! curl -sf http://127.0.0.1:{LIVEKIT_PORT}/health >/dev/null 2>&1; do echo "Waiting for LiveKit..."; sleep 1; done'
Restart=on-failure
RestartSec=10

[Install]
WantedBy=default.target
```

### launchd Template
```xml
<dict>
    <key>Label</key>
    <string>com.voicemode.livekit</string>
    <key>ProgramArguments</key>
    <array>
        <string>{LIVEKIT_BIN}</string>
        <string>--config</string>
        <string>{CONFIG_FILE}</string>
        <string>--dev</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
```

## Implementation Plan

### Phase 1: Core Installation
1. Create `voice_mode/tools/services/livekit/install.py`
   - Platform detection (macOS/Linux)
   - Binary installation (brew/curl/direct download)
   - Service file generation
   - Config file creation

2. Create `voice_mode/tools/services/livekit/uninstall.py`
   - Service removal
   - Binary cleanup
   - Config cleanup

### Phase 2: Service Management
1. Extend `voice_mode/tools/service.py`
   - Add LiveKit support
   - Health check integration
   - Status reporting

2. Create service templates
   - `voice_mode/templates/systemd/voicemode-livekit.service`
   - `voice_mode/templates/launchd/com.voicemode.livekit.plist`

### Phase 3: CLI Integration
1. Add to `voice_mode/cli.py`
   - Create `@voice_mode_main_cli.group()` for livekit
   - Add all subcommands (install, start, stop, etc.)

### Phase 4: MCP Tools
1. Create/update MCP tools
   - `install_livekit` tool
   - Update existing `service` tool
   - Add `livekit_status` tool

### Phase 5: Web Interface
1. Update web interface in `docs/web/`
   - Auto-detect local LiveKit server
   - Connection configuration
   - Fallback to cloud

## Health Checks

LiveKit exposes health endpoints:
- `/health` - Basic health check
- `/` - Returns LiveKit version info

## Auto-Discovery

Add to provider discovery:
- Check port 7880 for LiveKit server
- Verify with health endpoint
- Add to provider registry

## Testing Strategy

1. **Installation Testing**
   - Test on macOS (brew)
   - Test on Linux (curl script)
   - Test fallback binary download

2. **Service Testing**
   - Start/stop/restart
   - Auto-start on boot
   - Log rotation

3. **Integration Testing**
   - Web interface connection
   - Token generation
   - Room creation

## Migration from Previous Work

From the voice-mcp.tgz analysis:
- Reuse livekit-admin-mcp concepts for room management
- Adapt web interface from livekit/voice-assistant-frontend
- Use existing LiveKit documentation structure

## Success Metrics

- [ ] One-command installation: `voice-mode livekit install`
- [ ] Service management parity with Whisper/Kokoro
- [ ] Web interface works locally
- [ ] TailScale remote access functional
- [ ] Graceful fallback to cloud LiveKit

## Open Questions

1. Should we bundle the web interface or serve from docs/web/?
2. How to handle TURN server configuration for NAT traversal?
3. Should we auto-install during first `converse` if not present?

## Next Steps

1. Start with install.py implementation
2. Test on both macOS and Linux
3. Create service templates
4. Integrate with CLI
5. Update documentation