Kokoro TTS Server
Manage the Kokoro TTS HTTP server — an OpenAI-compatible /v1/audio/speech endpoint on localhost:8779.
Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
Server Overview
The server provides:
GET /health — Health status JSON
GET /v1/models — List available models
POST /v1/audio/speech — Synthesize text to audio (WAV, MP3, Opus, PCM)
Quick Start
Start (foreground, for testing)
~/.local/share/kokoro/.venv/bin/python ~/.local/share/kokoro/tts_server.py
Start (launchd, for production)
Per the macOS launchd policy, the launchd plist must launch a compiled Swift binary (not a bash script). Guide the user through:
- Compile Swift launcher binary
- Create launchd plist at
~/Library/LaunchAgents/com.terryli.kokoro-tts-server.plist
- Bootstrap:
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.terryli.kokoro-tts-server.plist
Stop
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.terryli.kokoro-tts-server.plist
Verify
curl -s http://127.0.0.1:8779/health | python3 -m json.tool
Expected: {"status": "ok", "provider": "kokoro-tts-mlx", "model": "mlx-community/Kokoro-82M-bf16", "device": "mlx-metal"}
Environment Variables
| Variable |
Default |
Purpose |
KOKORO_SERVER_PORT |
8779 |
Listen port |
KOKORO_SERVER_HOST |
127.0.0.1 |
Bind address |
KOKORO_DEFAULT_VOICE |
af_heart |
Default voice |
KOKORO_DEFAULT_LANG |
en-us |
Default language |
KOKORO_DEFAULT_SPEED |
1.0 |
Speech speed (0.1–5.0) |
KOKORO_PLAY_LOCAL |
0 |
Play via afplay |
Troubleshooting
| Issue |
Cause |
Solution |
| Port already in use |
Another server running |
lsof -i :8779 to find, kill it |
| Model load fails |
Not installed |
Run /kokoro-tts:install first |
| Slow first request |
Warmup synthesis |
Normal — first request triggers model load |
Post-Execution Reflection
After this skill completes, check before closing:
- Did the command succeed? — If not, fix the instruction or error table that caused the failure.
- Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
- Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.
Only update if the issue is real and reproducible — not speculative.
1---
2name: server
3description: "Start/stop Kokoro TTS HTTP server. TRIGGERS - start tts server, kokoro server, tts http, stop tts server."
4allowed-tools: Read, Write, Edit, Bash, Glob, AskUserQuestion
5metadata:
6 source: https://skillmd.com/skills/terrylica/server
7---
8
9# Kokoro TTS Server
10
11Manage the Kokoro TTS HTTP server — an OpenAI-compatible `/v1/audio/speech` endpoint on localhost:8779.
12
13> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
14
15## Server Overview
16
17The server provides:
18
19- `GET /health` — Health status JSON
20- `GET /v1/models` — List available models
21- `POST /v1/audio/speech` — Synthesize text to audio (WAV, MP3, Opus, PCM)
22
23## Quick Start
24
25### Start (foreground, for testing)
26
27```bash
28~/.local/share/kokoro/.venv/bin/python ~/.local/share/kokoro/tts_server.py
29```
30
31### Start (launchd, for production)
32
33Per the macOS launchd policy, the launchd plist must launch a compiled Swift binary (not a bash script). Guide the user through:
34
351. Compile Swift launcher binary
362. Create launchd plist at `~/Library/LaunchAgents/com.terryli.kokoro-tts-server.plist`
373. Bootstrap: `launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.terryli.kokoro-tts-server.plist`
38
39### Stop
40
41```bash
42launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.terryli.kokoro-tts-server.plist
43```
44
45### Verify
46
47```bash
48curl -s http://127.0.0.1:8779/health | python3 -m json.tool
49```
50
51Expected: `{"status": "ok", "provider": "kokoro-tts-mlx", "model": "mlx-community/Kokoro-82M-bf16", "device": "mlx-metal"}`
52
53## Environment Variables
54
55| Variable | Default | Purpose |
56| ---------------------- | ----------- | ---------------------- |
57| `KOKORO_SERVER_PORT` | `8779` | Listen port |
58| `KOKORO_SERVER_HOST` | `127.0.0.1` | Bind address |
59| `KOKORO_DEFAULT_VOICE` | `af_heart` | Default voice |
60| `KOKORO_DEFAULT_LANG` | `en-us` | Default language |
61| `KOKORO_DEFAULT_SPEED` | `1.0` | Speech speed (0.1–5.0) |
62| `KOKORO_PLAY_LOCAL` | `0` | Play via afplay |
63
64## Troubleshooting
65
66| Issue | Cause | Solution |
67| ------------------- | ---------------------- | ------------------------------------------ |
68| Port already in use | Another server running | `lsof -i :8779` to find, kill it |
69| Model load fails | Not installed | Run `/kokoro-tts:install` first |
70| Slow first request | Warmup synthesis | Normal — first request triggers model load |
71
72
73## Post-Execution Reflection
74
75After this skill completes, check before closing:
76
771. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure.
782. **Did parameters or output change?** — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
793. **Was a workaround needed?** — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.
80
81Only update if the issue is real and reproducible — not speculative.