create-local-voice-agent 1.0.0

package/README.md

@@ -0,0 +1,73 @@
+# create-voice-agent
+
+A CLI that scaffolds a **production-ready, containerized infrastructure** for real-time Voice AI Agents using **LiveKit**, **Python**, and **Docker**.
+
+Stop fighting WebRTC UDP port exhaustion, Docker permission errors, and token handshake wiring — this tool generates a perfect boilerplate in seconds.
+
+## Quick Start
+
+```bash
+npx create-voice-agent my-voice-app
+```
+
+You'll be prompted to choose:
+
+1. **LLM Provider** — Ollama (local GPU) or OpenAI (cloud)
+2. **Next.js Frontend** — optional browser UI with LiveKit Room components
+
+Then:
+
+```bash
+cd my-voice-app
+cp .env.example .env    # fill in your API keys
+docker compose up --build
+```
+
+## What Gets Generated
+
+```
+my-voice-app/
+├── docker-compose.yml          # LiveKit + Redis + Agent (+ Frontend)
+├── .env.example                # Pre-configured environment variables
+├── README.md                   # Project-specific documentation
+├── python-agent/
+│   ├── Dockerfile              # Non-root user (EACCES fix)
+│   ├── requirements.txt        # livekit-agents + plugins
+│   └── agent.py                # VoicePipelineAgent (VAD→STT→LLM→TTS)
+└── frontend/                   # (if selected)
+    ├── Dockerfile
+    ├── package.json            # includes livekit-server-sdk
+    ├── app/api/token/route.ts  # Secure AccessToken generation
+    └── app/page.tsx            # LiveKit Room + voice visualizer
+```
+
+## Key Architectural Decisions
+
+### WebRTC UDP Port Limiting
+LiveKit's UDP port range is strictly limited to `50000-50050` to prevent `docker-proxy` from spawning thousands of processes and hanging the host OS.
+
+### Token Handshake
+The Next.js frontend includes a `/api/token` endpoint using `livekit-server-sdk` to generate `AccessToken` JWTs. The browser fetches this token before connecting to the LiveKit room.
+
+### Non-Root Docker User
+The Python agent Dockerfile creates a dedicated `agentuser` to prevent `EACCES` permission errors common on Linux hosts.
+
+### Ollama GPU Routing
+When Ollama is selected, the agent container uses `host.docker.internal` to reach the host's GPU-accelerated Ollama instance.
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/geladons/create-voice-agent.git
+cd create-voice-agent
+npm install
+
+# Run locally
+node bin/create-voice-agent.js my-test-project
+```
+
+## License
+
+MIT
+

package/bin/create-voice-agent.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+import '../src/index.js';
+

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "create-local-voice-agent",
+  "version": "1.0.0",
+  "description": "CLI to scaffold production-ready, containerized Voice AI Agents using LiveKit, Python, and Docker",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "create-voice-agent": "./bin/create-voice-agent.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "livekit",
+    "voice-agent",
+    "webrtc",
+    "docker",
+    "cli",
+    "scaffold",
+    "ai"
+  ],
+  "author": "",
+  "license": "MIT",
+  "files": [
+    "bin/",
+    "src/",
+    "templates/"
+  ],
+  "dependencies": {
+    "@inquirer/prompts": "^8.3.0",
+    "commander": "^14.0.3",
+    "ejs": "^4.0.1"
+  }
+}

package/src/index.js

@@ -0,0 +1,310 @@
+import { Command } from 'commander';
+import { select, input, confirm } from '@inquirer/prompts';
+import { execSync } from 'node:child_process';
+import { scaffold } from './scaffold.js';
+
+// ─── Ollama API Fetching ──────────────────────────────────────────────
+async function fetchOllamaModels(ollamaIp = '127.0.0.1') {
+  try {
+    const url = `http://${ollamaIp}:11434/api/tags`;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3000);
+    const res = await fetch(url, { signal: controller.signal });
+    clearTimeout(timeout);
+    if (!res.ok) return [];
+    const data = await res.json();
+    return (data.models || []).map((m) => m.name);
+  } catch {
+    return [];
+  }
+}
+
+// ─── Model Selection Prompt ───────────────────────────────────────────
+async function promptModelName(models, defaultModel) {
+  if (models.length > 0) {
+    const choices = models.map((m) => ({ name: m, value: m }));
+    choices.push({ name: '✏️  Enter custom model name', value: '__custom__' });
+    const picked = await select({
+      message: 'Select an Ollama model:',
+      choices,
+    });
+    if (picked === '__custom__') {
+      return input({ message: 'Enter model name:', default: defaultModel });
+    }
+    return picked;
+  }
+  return input({ message: 'Enter Ollama model name:', default: defaultModel });
+}
+
+// ─── Docker Auto-Start ────────────────────────────────────────────────
+function autoStartDocker(projectName, deploymentType, modelName) {
+  const cwd = projectName;
+  console.log('\n🐳 Starting Docker containers...\n');
+
+  try {
+    // Copy .env.example to .env
+    execSync('cp .env.example .env', { cwd, stdio: 'inherit' });
+
+    if (deploymentType === 'standalone') {
+      // Start ollama container first
+      console.log('⏳ Starting Ollama container...');
+      execSync('docker compose up -d ollama', { cwd, stdio: 'inherit' });
+
+      // Wait for Ollama to be ready
+      console.log('⏳ Waiting for Ollama to be ready...');
+      let ready = false;
+      for (let i = 0; i < 30; i++) {
+        try {
+          execSync('docker compose exec ollama ollama list', {
+            cwd,
+            stdio: 'pipe',
+          });
+          ready = true;
+          break;
+        } catch {
+          execSync('sleep 2', { stdio: 'pipe' });
+        }
+      }
+      if (!ready) {
+        console.log('⚠️  Ollama container took too long to start. Pull model manually.');
+      } else {
+        // Pull the model
+        console.log(`⏳ Pulling model "${modelName}" (this may take a while)...`);
+        execSync(`docker compose exec ollama ollama pull ${modelName}`, {
+          cwd,
+          stdio: 'inherit',
+        });
+      }
+    }
+
+    // Start all services
+    console.log('\n🚀 Starting all services...');
+    execSync('docker compose up --build -d', { cwd, stdio: 'inherit' });
+    console.log('\n✅ All services are running!');
+    console.log('   LiveKit:  ws://localhost:7880');
+    console.log('   Frontend: http://localhost:3000 (if included)');
+  } catch (err) {
+    console.error('\n⚠️  Docker auto-start failed:', err.message);
+    console.log('   You can start manually with: docker compose up --build');
+  }
+}
+
+// ─── CLI Entry Point ──────────────────────────────────────────────────
+const program = new Command();
+
+program
+  .name('create-voice-agent')
+  .description(
+    'Scaffold a production-ready, containerized Voice AI Agent using LiveKit, Python, and Docker',
+  )
+  .version('1.0.0')
+  .argument('<project-name>', 'Name of the project directory to create')
+  .action(async (projectName) => {
+    console.log('\n🎙️  create-voice-agent v1.0.0\n');
+    console.log(`Scaffolding project: ${projectName}\n`);
+
+    // ─── Fetch Ollama models in background ────────────────────────
+    let ollamaModels = await fetchOllamaModels();
+    if (ollamaModels.length > 0) {
+      console.log(`✅ Ollama detected — ${ollamaModels.length} model(s) available\n`);
+    } else {
+      console.log('ℹ️  Ollama not detected on localhost (will ask later)\n');
+    }
+
+    // ─── Step 1: Setup Mode ───────────────────────────────────────
+    const setupMode = await select({
+      message: 'Select setup mode:',
+      choices: [
+        {
+          name: '⚡ Auto Mode (1-Click Magic)',
+          value: 'auto',
+          description: 'Ollama + defaults + auto-start Docker',
+        },
+        {
+          name: '🔧 Advanced Mode',
+          value: 'advanced',
+          description: 'Full control over every option',
+        },
+        {
+          name: '📦 Fast Mode (Scaffold Only)',
+          value: 'fast',
+          description: 'Generate files and exit — no auto-start',
+        },
+      ],
+    });
+
+    let llmProvider = 'ollama';
+    let deploymentType = null;
+    let modelName = 'qwen3-vl:2b';
+    let language = 'en';
+    let includeFrontend = true;
+    let shouldAutoStart = false;
+    let ollamaIp = 'localhost';
+
+    // ─── AUTO MODE ────────────────────────────────────────────────
+    if (setupMode === 'auto') {
+      llmProvider = 'ollama';
+      includeFrontend = true;
+      shouldAutoStart = true;
+
+      deploymentType = await select({
+        message: 'How do you want to run Ollama?',
+        choices: [
+          {
+            name: '🖥️  Use Existing Local Ollama (host)',
+            value: 'existing',
+            description: 'Ollama is already running on your machine',
+          },
+          {
+            name: '🐳 Install Standalone in Docker (CPU/GPU)',
+            value: 'standalone',
+            description: 'Ollama runs as a Docker service',
+          },
+        ],
+      });
+
+      if (deploymentType === 'existing') {
+        ollamaIp = await input({
+          message: 'Ollama IP address:',
+          default: 'localhost',
+        });
+        // Re-fetch models if IP changed
+        const fetchIp = ollamaIp === 'localhost' ? '127.0.0.1' : ollamaIp;
+        ollamaModels = await fetchOllamaModels(fetchIp);
+        modelName = await promptModelName(ollamaModels, 'qwen3-vl:2b');
+      } else {
+        modelName = 'qwen3-vl:2b';
+        console.log(`\n📦 Standalone mode: will use model "${modelName}" (fastest CPU model)`);
+      }
+    }
+
+    // ─── ADVANCED MODE ────────────────────────────────────────────
+    if (setupMode === 'advanced') {
+      llmProvider = await select({
+        message: 'Which LLM Provider?',
+        choices: [
+          { name: 'Ollama (Local)', value: 'ollama' },
+          { name: 'OpenAI (Cloud)', value: 'openai' },
+        ],
+      });
+
+      if (llmProvider === 'ollama') {
+        deploymentType = await select({
+          message: 'How do you want to run Ollama?',
+          choices: [
+            {
+              name: '🖥️  Use Existing Local Ollama (host)',
+              value: 'existing',
+              description: 'Ollama is already running on your machine',
+            },
+            {
+              name: '🐳 Install Standalone in Docker (CPU/GPU)',
+              value: 'standalone',
+              description: 'Ollama runs as a Docker service',
+            },
+          ],
+        });
+
+        ollamaIp = await input({
+          message: 'Ollama IP address:',
+          default: 'localhost',
+        });
+
+        if (deploymentType === 'existing') {
+          const fetchIp = ollamaIp === 'localhost' ? '127.0.0.1' : ollamaIp;
+          ollamaModels = await fetchOllamaModels(fetchIp);
+          modelName = await promptModelName(ollamaModels, 'qwen3-vl:4b');
+        } else {
+          modelName = await input({
+            message: 'Enter Ollama model name:',
+            default: 'qwen3-vl:4b',
+          });
+        }
+
+        language = await input({
+          message: 'Agent language (e.g., en, ru, de):',
+          default: 'en',
+        });
+      }
+
+      includeFrontend = await confirm({
+        message: 'Include a Next.js frontend?',
+        default: true,
+      });
+
+      if (llmProvider === 'ollama') {
+        shouldAutoStart = await confirm({
+          message: 'Auto-start Docker containers now?',
+          default: true,
+        });
+      }
+    }
+
+    // ─── FAST MODE ────────────────────────────────────────────────
+    if (setupMode === 'fast') {
+      llmProvider = await select({
+        message: 'Which LLM Provider?',
+        choices: [
+          { name: 'Ollama (Local)', value: 'ollama' },
+          { name: 'OpenAI (Cloud)', value: 'openai' },
+        ],
+      });
+
+      if (llmProvider === 'ollama') {
+        deploymentType = await select({
+          message: 'How do you want to run Ollama?',
+          choices: [
+            {
+              name: '🖥️  Use Existing Local Ollama (host)',
+              value: 'existing',
+            },
+            {
+              name: '🐳 Install Standalone in Docker (CPU/GPU)',
+              value: 'standalone',
+            },
+          ],
+        });
+      }
+
+      includeFrontend = await confirm({
+        message: 'Include a Next.js frontend?',
+        default: true,
+      });
+
+      // Fast mode uses defaults for model, language, no auto-start
+      modelName = deploymentType === 'standalone' ? 'qwen3-vl:2b' : 'qwen3-vl:4b';
+      shouldAutoStart = false;
+    }
+
+    // ─── Scaffold ─────────────────────────────────────────────────
+    await scaffold({
+      projectName,
+      llmProvider,
+      includeFrontend,
+      deploymentType,
+      modelName,
+      language,
+      ollamaIp,
+    });
+
+    console.log(`\n✅ Project "${projectName}" created successfully!\n`);
+
+    if (shouldAutoStart) {
+      autoStartDocker(projectName, deploymentType, modelName);
+    } else {
+      console.log('Next steps:');
+      console.log(`  cd ${projectName}`);
+      console.log('  cp .env.example .env');
+      if (llmProvider === 'openai') {
+        console.log('  # Fill in your API keys in .env');
+      } else {
+        console.log('  # No external API keys required — 100% local!');
+        if (deploymentType === 'existing') {
+          console.log('  # Make sure Ollama is running on your host machine');
+        }
+      }
+      console.log('  docker compose up --build\n');
+    }
+  });
+
+program.parse();

package/src/scaffold.js

@@ -0,0 +1,98 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import ejs from 'ejs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+
+/**
+ * Directories that should only be included for the local/ollama path.
+ */
+const LOCAL_ONLY_DIRS = ['custom_tts', 'custom_stt'];
+
+/**
+ * Recursively render all .ejs templates from a source directory into a target directory.
+ */
+function renderDir(srcDir, destDir, data) {
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    if (entry.isDirectory()) {
+      // Skip local-only directories when using cloud provider
+      if (LOCAL_ONLY_DIRS.includes(entry.name) && data.llmProvider !== 'ollama') {
+        continue;
+      }
+      const childDest = path.join(destDir, entry.name);
+      fs.mkdirSync(childDest, { recursive: true });
+      renderDir(srcPath, childDest, data);
+    } else if (entry.name.endsWith('.ejs')) {
+      const outName = entry.name.replace(/\.ejs$/, '');
+      const template = fs.readFileSync(srcPath, 'utf-8');
+      const rendered = ejs.render(template, data);
+      fs.writeFileSync(path.join(destDir, outName), rendered);
+    } else {
+      // Copy non-template files as-is
+      fs.copyFileSync(srcPath, path.join(destDir, entry.name));
+    }
+  }
+}
+
+/**
+ * Main scaffolding function.
+ */
+export async function scaffold({
+  projectName,
+  llmProvider,
+  includeFrontend,
+  deploymentType = null,
+  modelName = 'qwen3-vl:2b',
+  language = 'en',
+  ollamaIp = 'localhost',
+}) {
+  const projectDir = path.resolve(process.cwd(), projectName);
+
+  if (fs.existsSync(projectDir)) {
+    console.error(`\n❌ Directory "${projectName}" already exists. Aborting.`);
+    process.exit(1);
+  }
+
+  fs.mkdirSync(projectDir, { recursive: true });
+
+  const data = {
+    projectName,
+    llmProvider,
+    includeFrontend,
+    deploymentType,
+    modelName,
+    language,
+    ollamaIp,
+  };
+
+  // Render root-level templates
+  const rootTemplates = ['docker-compose.yml.ejs', '.env.example.ejs', 'README.md.ejs'];
+  for (const tpl of rootTemplates) {
+    const template = fs.readFileSync(path.join(TEMPLATES_DIR, tpl), 'utf-8');
+    const rendered = ejs.render(template, data);
+    const outName = tpl.replace(/\.ejs$/, '');
+    fs.writeFileSync(path.join(projectDir, outName), rendered);
+  }
+
+  // Render python-agent directory
+  const agentSrc = path.join(TEMPLATES_DIR, 'python-agent');
+  const agentDest = path.join(projectDir, 'python-agent');
+  fs.mkdirSync(agentDest, { recursive: true });
+  renderDir(agentSrc, agentDest, data);
+
+  // Render frontend directory (if selected)
+  if (includeFrontend) {
+    const frontendSrc = path.join(TEMPLATES_DIR, 'frontend');
+    const frontendDest = path.join(projectDir, 'frontend');
+    fs.mkdirSync(frontendDest, { recursive: true });
+    renderDir(frontendSrc, frontendDest, data);
+  }
+
+  console.log(`\n📁 Generated files in ./${projectName}/`);
+}
+

package/templates/.env.example.ejs

@@ -0,0 +1,22 @@
+# ─── LiveKit Credentials ─────────────────────────────────────────────
+# Generate a key/secret pair or use defaults for local development.
+LIVEKIT_API_KEY=devkey
+LIVEKIT_API_SECRET=devsecret
+
+<% if (llmProvider === 'openai') { -%>
+# ─── OpenAI ──────────────────────────────────────────────────────────
+OPENAI_API_KEY=sk-your-openai-api-key-here
+<% } else if (deploymentType === 'standalone') { -%>
+# ─── Ollama (Standalone Docker) ─────────────────────────────────────
+# The agent connects to the Ollama container via Docker networking.
+# No need to change this — it is set automatically in docker-compose.yml.
+OLLAMA_BASE_URL=http://localhost:11434
+<% } else { -%>
+# ─── Ollama (Existing Host) ─────────────────────────────────────────
+# Points to the host machine's Ollama instance from inside Docker.
+<% if (ollamaIp === 'localhost' || ollamaIp === '127.0.0.1') { -%>
+OLLAMA_BASE_URL=http://host.docker.internal:11434
+<% } else { -%>
+OLLAMA_BASE_URL=http://<%= ollamaIp %>:11434
+<% } -%>
+<% } -%>

package/templates/README.md.ejs

@@ -0,0 +1,60 @@
+# <%= projectName %>
+
+A real-time Voice AI Agent powered by [LiveKit](https://livekit.io/), Python, and Docker.
+
+## Architecture
+
+- **LiveKit Server** — WebRTC media server (SFU)
+- **Redis** — Required by LiveKit for signaling
+- **Python Agent** — Voice pipeline using `livekit-agents` (VAD → STT → LLM → TTS)
+<% if (includeFrontend) { -%>
+- **Next.js Frontend** — Browser UI with LiveKit Room components
+<% } -%>
+
+## Quick Start
+
+```bash
+# 1. Copy and configure environment variables
+cp .env.example .env
+# Edit .env with your API keys
+
+# 2. Start all services
+docker compose up --build
+```
+
+<% if (llmProvider === 'ollama') { -%>
+### Ollama (Local LLM)
+
+Make sure Ollama is running on your host machine:
+
+```bash
+ollama serve
+ollama pull llama3.1
+```
+
+The agent connects to Ollama via `http://host.docker.internal:11434`.
+<% } else { -%>
+### OpenAI
+
+Set your `OPENAI_API_KEY` in the `.env` file.
+<% } -%>
+
+<% if (includeFrontend) { -%>
+## Frontend
+
+Open [http://localhost:3000](http://localhost:3000) in your browser.
+The frontend fetches a LiveKit access token from `/api/token` and connects to the voice agent.
+<% } -%>
+
+## Services & Ports
+
+| Service    | Port  | Protocol |
+| ---------- | ----- | -------- |
+| LiveKit    | 7880  | HTTP/WS  |
+| LiveKit    | 7881  | RTC TCP  |
+| LiveKit    | 50000-50050 | UDP |
+| Redis      | 6379  | TCP      |
+<% if (includeFrontend) { -%>
+| Frontend   | 3000  | HTTP     |
+<% } -%>
+

package/templates/docker-compose.yml.ejs

@@ -0,0 +1,100 @@
+version: "3.9"
+
+services:
+<% if (llmProvider === 'ollama' && deploymentType === 'standalone') { -%>
+  # ─── Ollama (Standalone) ─────────────────────────────────────────
+  ollama:
+    image: ollama/ollama
+    restart: unless-stopped
+    ports:
+      - "11434:11434"
+    volumes:
+      - ollama_data:/root/.ollama
+    deploy:
+      resources:
+        limits:
+          cpus: '10'
+
+<% } -%>
+  # ─── Redis (required by LiveKit) ───────────────────────────────────
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    ports:
+      - "6379:6379"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  # ─── LiveKit Server ────────────────────────────────────────────────
+  livekit:
+    image: livekit/livekit-server:latest
+    restart: unless-stopped
+    depends_on:
+      redis:
+        condition: service_healthy
+    ports:
+      - "7880:7880"       # HTTP / WebSocket
+      - "7881:7881"       # RTC TCP
+      - "50000-50050:50000-50050/udp"   # WebRTC UDP (strictly limited range)
+    environment:
+      - LIVEKIT_KEYS=${LIVEKIT_API_KEY}:${LIVEKIT_API_SECRET}
+    command: >
+      --config /etc/livekit.yaml
+      --bind 0.0.0.0
+      --redis-host redis:6379
+      --rtc.port-range-start 50000
+      --rtc.port-range-end 50050
+      --rtc.tcp-port 7881
+
+  # ─── Python Voice Agent ────────────────────────────────────────────
+  agent:
+    build:
+      context: ./python-agent
+      dockerfile: Dockerfile
+    restart: unless-stopped
+    depends_on:
+      - livekit
+<% if (llmProvider === 'ollama' && deploymentType === 'standalone') { -%>
+      - ollama
+<% } -%>
+    environment:
+      - LIVEKIT_URL=ws://livekit:7880
+      - LIVEKIT_API_KEY=${LIVEKIT_API_KEY}
+      - LIVEKIT_API_SECRET=${LIVEKIT_API_SECRET}
+<% if (llmProvider === 'ollama' && deploymentType === 'standalone') { -%>
+      - OLLAMA_BASE_URL=http://ollama:11434
+<% } else if (llmProvider === 'ollama' && deploymentType === 'existing') { -%>
+      - OLLAMA_BASE_URL=${OLLAMA_BASE_URL}
+<% } else { -%>
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+<% } -%>
+<% if (llmProvider === 'ollama' && deploymentType === 'existing') { -%>
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+<% } -%>
+
+<% if (includeFrontend) { -%>
+  # ─── Next.js Frontend ─────────────────────────────────────────────
+  frontend:
+    build:
+      context: ./frontend
+      dockerfile: Dockerfile
+    restart: unless-stopped
+    depends_on:
+      - livekit
+    ports:
+      - "3000:3000"
+    environment:
+      - LIVEKIT_API_KEY=${LIVEKIT_API_KEY}
+      - LIVEKIT_API_SECRET=${LIVEKIT_API_SECRET}
+      - LIVEKIT_URL=ws://livekit:7880
+      - NEXT_PUBLIC_LIVEKIT_URL=ws://localhost:7880
+<% } -%>
+
+<% if (llmProvider === 'ollama' && deploymentType === 'standalone') { -%>
+volumes:
+  ollama_data:
+<% } -%>

package/templates/frontend/Dockerfile.ejs

@@ -0,0 +1,13 @@
+FROM node:20-alpine
+
+WORKDIR /app
+
+COPY package.json package-lock.json* ./
+RUN npm install
+
+COPY . .
+
+EXPOSE 3000
+
+CMD ["npm", "run", "dev"]
+

package/templates/frontend/app/api/token/route.ts.ejs

@@ -0,0 +1,33 @@
+import { AccessToken } from "livekit-server-sdk";
+import { NextRequest, NextResponse } from "next/server";
+
+export async function GET(req: NextRequest) {
+  const room = req.nextUrl.searchParams.get("room") ?? "default-room";
+  const username = req.nextUrl.searchParams.get("username") ?? `user-${Math.floor(Math.random() * 10000)}`;
+
+  const apiKey = process.env.LIVEKIT_API_KEY;
+  const apiSecret = process.env.LIVEKIT_API_SECRET;
+
+  if (!apiKey || !apiSecret) {
+    return NextResponse.json(
+      { error: "LIVEKIT_API_KEY and LIVEKIT_API_SECRET must be set" },
+      { status: 500 }
+    );
+  }
+
+  const at = new AccessToken(apiKey, apiSecret, {
+    identity: username,
+  });
+
+  at.addGrant({
+    room,
+    roomJoin: true,
+    canPublish: true,
+    canSubscribe: true,
+  });
+
+  const token = await at.toJwt();
+
+  return NextResponse.json({ token });
+}
+

package/templates/frontend/app/layout.tsx

@@ -0,0 +1,17 @@
+export const metadata = {
+  title: "Voice Agent",
+  description: "Real-time Voice AI Agent",
+};
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+

package/templates/frontend/app/page.tsx.ejs

@@ -0,0 +1,90 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import {
+  LiveKitRoom,
+  RoomAudioRenderer,
+  useVoiceAssistant,
+  BarVisualizer,
+  DisconnectButton,
+} from "@livekit/components-react";
+import "@livekit/components-styles";
+
+function VoiceAssistantUI() {
+  const { state, audioTrack } = useVoiceAssistant();
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        gap: "1rem",
+        padding: "2rem",
+      }}
+    >
+      <h2>Agent Status: {state}</h2>
+      <BarVisualizer
+        state={state}
+        barCount={5}
+        trackRef={audioTrack}
+        style={{ width: "300px", height: "80px" }}
+      />
+      <DisconnectButton>Disconnect</DisconnectButton>
+    </div>
+  );
+}
+
+export default function Home() {
+  const [token, setToken] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const livekitUrl = process.env.NEXT_PUBLIC_LIVEKIT_URL ?? "ws://localhost:7880";
+
+  useEffect(() => {
+    async function fetchToken() {
+      try {
+        const res = await fetch("/api/token?room=voice-room&username=user");
+        if (!res.ok) throw new Error("Failed to fetch token");
+        const data = await res.json();
+        setToken(data.token);
+      } catch (err: unknown) {
+        setError(err instanceof Error ? err.message : "Unknown error");
+      }
+    }
+    fetchToken();
+  }, []);
+
+  if (error) {
+    return (
+      <div style={{ padding: "2rem", textAlign: "center" }}>
+        <h1>Error</h1>
+        <p>{error}</p>
+      </div>
+    );
+  }
+
+  if (!token) {
+    return (
+      <div style={{ padding: "2rem", textAlign: "center" }}>
+        <p>Connecting to voice agent...</p>
+      </div>
+    );
+  }
+
+  return (
+    <main style={{ padding: "2rem", textAlign: "center" }}>
+      <h1><%= projectName %></h1>
+      <LiveKitRoom
+        serverUrl={livekitUrl}
+        token={token}
+        connect={true}
+        audio={true}
+      >
+        <VoiceAssistantUI />
+        <RoomAudioRenderer />
+      </LiveKitRoom>
+    </main>
+  );
+}
+

package/templates/frontend/next.config.js

@@ -0,0 +1,5 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {};
+
+module.exports = nextConfig;
+

package/templates/frontend/package.json.ejs

@@ -0,0 +1,24 @@
+{
+  "name": "<%= projectName %>-frontend",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "next": "^15.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@livekit/components-react": "^2.0.0",
+    "livekit-client": "^2.0.0",
+    "livekit-server-sdk": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "typescript": "^5.0.0"
+  }
+}
+

package/templates/frontend/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": { "@/*": ["./*"] }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules"]
+}
+

package/templates/python-agent/Dockerfile.ejs

@@ -0,0 +1,35 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && \
+<% if (llmProvider === 'ollama') { -%>
+    apt-get install -y --no-install-recommends gcc ffmpeg libsndfile1-dev curl && \
+<% } else { -%>
+    apt-get install -y --no-install-recommends gcc && \
+<% } -%>
+    rm -rf /var/lib/apt/lists/*
+
+<% if (llmProvider === 'ollama') { -%>
+# Download Piper TTS voice model (en_US-lessac-medium)
+RUN mkdir -p /app/models && \
+    curl -L -o /app/models/en_US-lessac-medium.onnx \
+      "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/lessac/medium/en_US-lessac-medium.onnx" && \
+    curl -L -o /app/models/en_US-lessac-medium.onnx.json \
+      "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/lessac/medium/en_US-lessac-medium.onnx.json"
+
+<% } -%>
+# Copy and install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy agent source code
+COPY . .
+
+# ─── EACCES Fix: run as non-root user ───────────────────────────────
+RUN useradd -m agentuser && \
+    chown -R agentuser:agentuser /app
+USER agentuser
+
+CMD ["python", "agent.py", "start"]

package/templates/python-agent/agent.py.ejs

@@ -0,0 +1,63 @@
+"""
+<%= projectName %> — Voice AI Agent
+Uses the official livekit-agents library with VoicePipelineAgent.
+"""
+
+import os
+import logging
+
+from livekit.agents import AutoSubscribe, JobContext, WorkerOptions, cli
+from livekit.agents.pipeline import VoicePipelineAgent
+from livekit.plugins import silero
+<% if (llmProvider === 'openai') { -%>
+from livekit.plugins import deepgram
+from livekit.plugins import openai as openai_plugin
+<% } else { -%>
+from livekit.plugins import openai as openai_plugin
+from custom_stt.faster_whisper_stt import FasterWhisperSTT
+from custom_tts.piper_tts import PiperTTSPlugin
+<% } -%>
+
+logger = logging.getLogger("voice-agent")
+logger.setLevel(logging.INFO)
+
+
+async def entrypoint(ctx: JobContext):
+    """Called when a participant joins the LiveKit room."""
+
+    logger.info(f"Connecting to room: {ctx.room.name}")
+    await ctx.connect(auto_subscribe=AutoSubscribe.AUDIO_ONLY)
+
+    participant = await ctx.wait_for_participant()
+    logger.info(f"Participant joined: {participant.identity}")
+
+    # ─── Build the Voice Pipeline ────────────────────────────────────
+<% if (llmProvider === 'openai') { -%>
+    llm = openai_plugin.LLM(model="gpt-4o-mini")
+    tts_engine = openai_plugin.TTS(voice="alloy")
+    stt_engine = deepgram.STT()
+<% } else { -%>
+    # Model: <%= modelName %> | Language: <%= language %>
+    llm = openai_plugin.LLM.with_ollama(
+        model="<%= modelName %>",
+        base_url=os.environ.get("OLLAMA_BASE_URL", "http://host.docker.internal:11434"),
+    )
+    tts_engine = PiperTTSPlugin(model="/app/models/en_US-lessac-medium.onnx")
+    stt_engine = FasterWhisperSTT(model="base", language="<%= language %>")
+<% } -%>
+
+    agent = VoicePipelineAgent(
+        vad=silero.VAD.load(),
+        stt=stt_engine,
+        llm=llm,
+        tts=tts_engine,
+    )
+
+    # Start the agent in the room
+    agent.start(ctx.room, participant)
+
+    await agent.say("Hello! I'm your voice assistant. How can I help you today?")
+
+
+if __name__ == "__main__":
+    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))

package/templates/python-agent/custom_stt/__init__.py

@@ -0,0 +1 @@
+

package/templates/python-agent/custom_stt/faster_whisper_stt.py

@@ -0,0 +1,85 @@
+"""
+Faster Whisper STT Plugin for LiveKit Agents.
+Uses the faster-whisper Python package for fully offline speech-to-text.
+"""
+
+import asyncio
+import io
+import logging
+import wave
+
+import numpy as np
+from faster_whisper import WhisperModel
+
+from livekit.agents import stt
+from livekit.agents.types import DEFAULT_API_CONNECT_OPTIONS
+
+logger = logging.getLogger("faster-whisper-stt")
+
+
+class FasterWhisperSTT(stt.STT):
+    def __init__(self, model="base", language="en", device="cpu", compute_type="int8"):
+        super().__init__(
+            capabilities=stt.STTCapabilities(streaming=False, interim_results=False),
+        )
+        self.model_size = model
+        self.language = language
+        self.device = device
+        self.compute_type = compute_type
+        self._model = None
+        self._load_model()
+
+    def _load_model(self):
+        logger.info(f"Loading Whisper model: {self.model_size} (device={self.device})")
+        self._model = WhisperModel(
+            self.model_size,
+            device=self.device,
+            compute_type=self.compute_type,
+        )
+        logger.info("Whisper model loaded successfully")
+
+    async def recognize(self, buffer, *, language=None, conn_options=DEFAULT_API_CONNECT_OPTIONS):
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(
+            None, self._transcribe, buffer, language or self.language
+        )
+
+    def _transcribe(self, buffer, language):
+        # Convert LiveKit AudioFrame to numpy array
+        if hasattr(buffer, "data"):
+            audio_data = np.frombuffer(buffer.data, dtype=np.int16).astype(np.float32) / 32768.0
+            sample_rate = buffer.sample_rate if hasattr(buffer, "sample_rate") else 16000
+        elif hasattr(buffer, "frame"):
+            frame = buffer.frame
+            audio_data = np.frombuffer(frame.data, dtype=np.int16).astype(np.float32) / 32768.0
+            sample_rate = frame.sample_rate if hasattr(frame, "sample_rate") else 16000
+        else:
+            audio_data = np.frombuffer(buffer, dtype=np.int16).astype(np.float32) / 32768.0
+            sample_rate = 16000
+
+        # Resample to 16kHz if needed (Whisper expects 16kHz)
+        if sample_rate != 16000:
+            from scipy.signal import resample
+            num_samples = int(len(audio_data) * 16000 / sample_rate)
+            audio_data = resample(audio_data, num_samples).astype(np.float32)
+
+        segments, info = self._model.transcribe(
+            audio_data,
+            language=language,
+            beam_size=5,
+            vad_filter=True,
+        )
+
+        text = " ".join(segment.text for segment in segments).strip()
+
+        return stt.SpeechEvent(
+            type=stt.SpeechEventType.FINAL_TRANSCRIPT,
+            alternatives=[
+                stt.SpeechData(
+                    text=text,
+                    language=language or info.language,
+                    confidence=1.0,
+                )
+            ],
+        )
+

package/templates/python-agent/custom_tts/__init__.py

@@ -0,0 +1 @@
+

package/templates/python-agent/custom_tts/piper_tts.py

@@ -0,0 +1,104 @@
+"""
+Piper TTS Plugin for LiveKit Agents.
+Based on the community plugin by nay-cat/LiveKit-PiperTTS-Plugin.
+Uses the piper-tts Python package for fully offline text-to-speech.
+"""
+
+import numpy as np
+import asyncio
+import logging
+
+from livekit.agents import tts
+from livekit.agents.types import DEFAULT_API_CONNECT_OPTIONS
+from livekit import rtc
+from piper import PiperVoice, SynthesisConfig
+
+logger = logging.getLogger("piper-tts")
+
+
+class PiperTTSPlugin(tts.TTS):
+    def __init__(self, model, speed=1.0, volume=1.0, noise_scale=0.667, noise_w=0.8, use_cuda=False):
+        super().__init__(
+            capabilities=tts.TTSCapabilities(streaming=False),
+            sample_rate=22050,
+            num_channels=1,
+        )
+        self.model = model
+        self.speed = speed
+        self.volume = volume
+        self.noise_scale = noise_scale
+        self.noise_w = noise_w
+        self.use_cuda = use_cuda
+        self._voice = None
+        self._load_voice()
+
+    def _load_voice(self):
+        logger.info(f"Loading Piper voice model: {self.model}")
+        self._voice = PiperVoice.load(self.model, use_cuda=self.use_cuda)
+        logger.info("Piper voice model loaded successfully")
+
+    def synthesize(self, text, *, conn_options=DEFAULT_API_CONNECT_OPTIONS):
+        return PiperStream(self, text, conn_options)
+
+
+class PiperStream(tts.ChunkedStream):
+    def __init__(self, plugin, text, conn_options):
+        super().__init__(tts=plugin, input_text=text, conn_options=conn_options)
+        self.plugin = plugin
+
+    async def _run(self):
+        try:
+            config = SynthesisConfig(
+                volume=self.plugin.volume,
+                length_scale=self.plugin.speed,
+                noise_scale=self.plugin.noise_scale,
+                noise_w_scale=self.plugin.noise_w,
+                normalize_audio=True,
+            )
+
+            loop = asyncio.get_event_loop()
+            chunks = await loop.run_in_executor(None, self._synthesize_chunks, config)
+
+            for chunk in chunks:
+                frame = rtc.AudioFrame(
+                    data=chunk,
+                    sample_rate=22050,
+                    num_channels=1,
+                    samples_per_channel=len(chunk) // 2,
+                )
+                self._event_ch.send_nowait(
+                    tts.SynthesizedAudio(
+                        request_id="1",
+                        segment_id="1",
+                        frame=frame,
+                    )
+                )
+
+        except Exception as e:
+            logger.error(f"Piper TTS synthesis failed: {e}")
+            silence = np.zeros(22050, dtype=np.int16).tobytes()
+            frame = rtc.AudioFrame(
+                data=silence,
+                sample_rate=22050,
+                num_channels=1,
+                samples_per_channel=22050,
+            )
+            self._event_ch.send_nowait(
+                tts.SynthesizedAudio(
+                    request_id="1",
+                    segment_id="1",
+                    frame=frame,
+                )
+            )
+
+    def _synthesize_chunks(self, config):
+        chunks = []
+        for chunk in self.plugin._voice.synthesize(self.input_text, syn_config=config):
+            audio_data = chunk.audio_int16_bytes
+            if chunk.sample_channels == 2:
+                audio = np.frombuffer(audio_data, dtype=np.int16)
+                audio = audio.reshape(-1, 2).mean(axis=1).astype(np.int16)
+                audio_data = audio.tobytes()
+            chunks.append(audio_data)
+        return chunks
+

package/templates/python-agent/requirements.txt.ejs

@@ -0,0 +1,11 @@
+livekit-agents>=0.12.0
+livekit-plugins-silero>=0.7.0
+livekit-plugins-openai>=0.10.0
+<% if (llmProvider === 'openai') { -%>
+livekit-plugins-deepgram>=0.7.0
+<% } else { -%>
+piper-tts>=1.3.0
+faster-whisper>=1.0.0
+numpy
+onnxruntime>=1.22.0
+<% } -%>