# LiveKit Setup and Usage Guide

> This guide covers the complete setup and usage of LiveKit integration with Voice Mode, including the LiveKit server, frontend management, and voice conversations.

- Skill: `tools-only/livekit-setup-and-usage-guide` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/livekit-setup-and-usage-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/livekit-setup-and-usage-guide/raw
- Safety review: pending (external: skill-scanner PASS, skillspector WARNING)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/livekit-setup-and-usage-guide

---

# LiveKit Setup and Usage Guide

This guide covers the complete setup and usage of LiveKit integration with Voice Mode, including the LiveKit server, frontend management, and voice conversations.

## Overview

Voice Mode now includes full LiveKit integration providing:
- **LiveKit server management** - Install, configure, and manage LiveKit server as a system service
- **Voice Assistant Frontend** - Web-based interface for voice conversations bundled with Voice Mode
- **Service integration** - Unified management alongside Whisper and Kokoro services
- **Development and production** support with proper service lifecycle management

## Quick Start

### 1. Install LiveKit Server

```bash
# Install LiveKit server (automatically detects platform)
voice-mode livekit install

# Enable to start at boot/login
voice-mode livekit enable

# Start the server
voice-mode livekit start
```

### 2. Start Frontend

```bash
# Start the Voice Assistant Frontend
voice-mode frontend start

# Enable to start automatically
voice-mode frontend enable

# Open in browser
voice-mode frontend open
```

### 3. Access Voice Interface

1. Open http://localhost:3000 in your browser
2. Enter password: `voicemode123` (default)
3. Join or create a room for voice conversations

## Installation Details

### LiveKit Server Installation

The `voice-mode livekit install` command:
- Downloads LiveKit server binary for your platform (macOS/Linux)
- Creates configuration file at `~/.voicemode/config/livekit.yaml`
- Sets up systemd (Linux) or launchd (macOS) service files
- Configures development credentials for easy setup

**Installation locations:**
- **macOS**: `/opt/homebrew/bin/livekit-server`
- **Linux**: `/usr/local/bin/livekit-server`
- **Config**: `~/.voicemode/config/livekit.yaml`
- **Logs**: `~/.voicemode/logs/livekit/`

### Frontend Installation

The frontend is bundled with Voice Mode and automatically installed. The system:
- Prioritizes bundled frontend in the Python package
- Falls back to external development locations if needed
- Automatically installs Node.js dependencies on first run
- Supports multiple package managers (pnpm, npm, yarn)

## Configuration

### LiveKit Server Configuration

Edit `~/.voicemode/config/livekit.yaml`:

```yaml
# LiveKit development configuration
port: 7880
rtc:
  port_range_start: 50000
  port_range_end: 50100

keys:
  devkey: secret

# Enable room auto-creation for development
room:
  auto_create: true

# Development logging
logging:
  level: info
  json: false
```

### Frontend Configuration

Create `~/.voicemode/frontend/.env.local` for custom settings:

```bash
# Custom password (optional)
LIVEKIT_ACCESS_PASSWORD=your_custom_password

# LiveKit server URL (if different)
LIVEKIT_SERVER_URL=ws://localhost:7880
```

## Service Management

All LiveKit services integrate with Voice Mode's unified service management:

### Server Commands

```bash
# Status and control
voice-mode livekit status
voice-mode livekit start
voice-mode livekit stop
voice-mode livekit restart

# Service management
voice-mode livekit enable    # Start at boot/login
voice-mode livekit disable   # Don't start automatically

# Logs
voice-mode livekit logs
voice-mode livekit logs --follow
```

### Frontend Commands

```bash
# Status and control
voice-mode frontend status
voice-mode frontend start
voice-mode frontend stop

# Service management
voice-mode frontend enable
voice-mode frontend disable

# Utilities
voice-mode frontend open     # Open in browser
voice-mode frontend logs     # View logs
voice-mode frontend logs -f  # Follow logs
```

### Service Integration

Both LiveKit and frontend services work with the unified service management:

```bash
# Using the service command
voice-mode service livekit status
voice-mode service frontend start
voice-mode service frontend enable
```

## Usage Scenarios

### Development Setup

For active development:

```bash
# Quick start everything
voice-mode livekit start
voice-mode frontend start

# Open the interface
voice-mode frontend open
```

### Production Deployment

For persistent services:

```bash
# Install and enable all services
voice-mode livekit install
voice-mode livekit enable

voice-mode frontend enable

# Services now start automatically at boot/login
# Status check
voice-mode livekit status
voice-mode frontend status
```

### Troubleshooting Setup

```bash
# Check all service status
voice-mode livekit status
voice-mode frontend status

# View logs for issues
voice-mode livekit logs --follow
voice-mode frontend logs --follow

# Restart services
voice-mode livekit restart
voice-mode frontend restart
```

## Voice Conversations

### Web Interface

1. **Access**: Navigate to http://localhost:3000
2. **Authentication**: Enter password (default: `voicemode123`)
3. **Room Management**: Create or join rooms for conversations
4. **Voice Control**: Click to start/stop recording and speaking

### API Integration

LiveKit server provides REST API and WebSocket endpoints:

```bash
# List active rooms
curl -H "Authorization: Bearer <jwt_token>" \
     http://localhost:7880/twirp/livekit.RoomService/ListRooms \
     -H "Content-Type: application/json" -d '{}'
```

**Generate JWT tokens** for API access using development credentials:
- **Key**: `devkey`
- **Secret**: `secret`

### Frontend Features

- **Real-time voice conversations** with AI agents
- **Room-based communication** supporting multiple participants
- **Automatic room creation** for quick setup
- **Responsive web interface** optimized for voice interactions
- **WebRTC audio** with LiveKit's optimized transport

## Advanced Configuration

### Custom Ports

To change default ports, edit configurations and restart services:

**LiveKit server** (`~/.voicemode/config/livekit.yaml`):
```yaml
port: 8880  # Change from default 7880
```

**Frontend** (`.env.local`):
```bash
PORT=4000  # Change from default 3000
```

### SSL/TLS Setup

For production deployments with SSL:

1. Configure reverse proxy (nginx, Apache)
2. Update frontend LIVEKIT_SERVER_URL to use wss://
3. Ensure LiveKit server accepts secure connections

### Multiple Instances

Run multiple LiveKit instances:

```bash
# Custom config file
livekit-server --config /path/to/custom-config.yaml

# Different ports
# Edit config files to use different port ranges
```

## Logs and Monitoring

### Log Locations

- **LiveKit server**: `~/.voicemode/logs/livekit/livekit.log`
- **Frontend**: `~/.voicemode/logs/frontend/frontend.log`
- **System services**: `journalctl --user -u voicemode-livekit.service`

### Health Checks

```bash
# Check if services are responding
curl -f http://localhost:7880/debug/info || echo "LiveKit not responding"
curl -f http://localhost:3000 || echo "Frontend not responding"

# Check process status
voice-mode livekit status
voice-mode frontend status
```

### Performance Monitoring

Monitor resource usage:

```bash
# Service memory and CPU usage
voice-mode livekit status    # Shows memory/CPU
voice-mode frontend status   # Shows resource usage

# System monitoring
ps aux | grep livekit
ps aux | grep next-server    # Frontend process
```

## Uninstallation

### Remove Services

```bash
# Disable and stop services
voice-mode livekit disable
voice-mode livekit stop
voice-mode frontend disable

# Uninstall (removes binaries and configs)
voice-mode livekit uninstall
voice-mode livekit uninstall --remove-all-data  # Includes logs
```

### Clean Removal

Complete cleanup:

```bash
# Remove all LiveKit data
rm -rf ~/.voicemode/logs/livekit/
rm -rf ~/.voicemode/config/livekit.yaml

# Remove frontend data  
rm -rf ~/.voicemode/logs/frontend/

# Remove service files (automatic on uninstall)
```

## Integration with Voice Mode

### MCP Tools

LiveKit services are available as MCP tools for AI agents:

- `livekit_install` / `livekit_uninstall`
- `livekit_server_start` / `livekit_server_stop` / `livekit_server_status`
- `livekit_frontend_start` / `livekit_frontend_stop` / `livekit_frontend_status`
- `livekit_frontend_open` / `livekit_frontend_logs`

### Agent Integration

AI agents can manage LiveKit services programmatically and create voice conversation rooms for direct interaction.

## Troubleshooting

### Common Issues

**Port already in use:**
```bash
# Find conflicting process
lsof -ti :7880  # LiveKit
lsof -ti :3000  # Frontend

# Stop conflicting services
voice-mode livekit stop
voice-mode frontend stop
```

**Permission denied:**
```bash
# Fix service permissions (Linux)
systemctl --user daemon-reload
systemctl --user restart voicemode-livekit.service

# Fix binary permissions
sudo chmod +x /usr/local/bin/livekit-server
```

**Frontend dependencies:**
```bash
# Manual dependency install
cd ~/.voicemode/frontend  # or bundled location
npm install

# Check frontend logs
voice-mode frontend logs
```

**Service won't start:**
```bash
# Check service status
systemctl --user status voicemode-livekit.service
systemctl --user status voicemode-frontend.service

# View system logs
journalctl --user -u voicemode-livekit.service -f
```

### Getting Help

1. **Check logs first**: `voice-mode livekit logs` and `voice-mode frontend logs`
2. **Verify installation**: `voice-mode livekit status`
3. **Test connectivity**: Access http://localhost:3000 and http://localhost:7880
4. **Review configuration**: Check `~/.voicemode/config/livekit.yaml`

For additional support, include log outputs and system information when reporting issues.