ForgeGuard Kokoro Server

Overview

What it solves.

ForgeGuard Kokoro Server exposes an OpenAI-style /v1/audio/speech endpoint so any OpenAI SDK or compatible client can synthesize speech against local hardware. It solves the operational half of self-hosted TTS: images with weights baked in, health and readiness endpoints designed for orchestrators, optional bearer authentication, built-in HTTPS, and GPU telemetry for the bundled web console.

Distribution is deliberately narrow — container images and a Helm chart only. There is no supported bare-metal install path, which keeps the deployment story reproducible on both x86_64 CUDA workstations and Jetson Orin edge devices.

Verified capabilities

What it does.

• OpenAI-compatible speech APIPOST /v1/audio/speech with streaming responses in mp3, wav, opus, flac, and raw 16-bit 24 kHz PCM; point any OpenAI SDK at the server.
• Multi-language synthesisEnglish (US/GB), Spanish, French, Hindi, Italian, Japanese, Brazilian Portuguese, and Mandarin Chinese via the Kokoro-82M model.
• Voice mixing and voicepacksWeighted voice combinations like af_bella(2)+af_sky(1), with /v1/audio/voices/combine to persist a blend as a reusable voicepack.
• Timestamped captions and phoneme control/dev/captioned_speech returns word-level timestamps; /dev/phonemize and /dev/generate_from_phonemes give IPA-level input and output control.
• Warmup-aware health contractThe server accepts connections immediately while the model warms in the background; /health, /ready, and Retry-After semantics keep orchestrator probes accurate, and a failed warmup exits non-zero instead of lingering unhealthy.
• Optional bearer authentication and built-in HTTPSA single API_KEY environment variable gates API routes; TLS_ENABLED=true serves HTTPS directly with an auto-generated, persisted self-signed certificate by default.
• Inline pause and pronunciation tokens"[pause:1.5s]" inserts silence and "[Worcester](/wˈʊstər/)" overrides pronunciation with IPA, parsed server-side during synthesis.
• Long-form chunkingInput is split and stitched at sentence boundaries with configurable token bounds, compensating for the model's ~30-second tuning window.

Operational facts

The operating contract.

Evidence

Console and request contract.

curl -X POST http://localhost:8880/v1/audio/speech \
  -H 'Content-Type: application/json' \
  -d '{"model":"kokoro","input":"Hello world!","voice":"af_heart","response_format":"mp3"}' \
  -o hello.mp3

Architecture

Data flow.

Clients speak the OpenAI API to a FastAPI interface layer that handles auth, queuing, and format negotiation; inference runs on local GPU compute with health and telemetry surfaced alongside.

Deployment

Deployment paths.

docker run -d --name kokoro --gpus all -p 8880:8880 \
  ghcr.io/forgeguard-ai/kokoro-server:latest

docker run -d --name kokoro --runtime nvidia -p 8880:8880 \
  ghcr.io/forgeguard-ai/kokoro-server-jetson:latest

docker compose -f docker/gpu/docker-compose.prod.yml up -d

helm install kokoro oci://ghcr.io/forgeguard-ai/charts/kokoro-server --version 1.1.0

Compatibility

Support matrix.

Lineage & attribution

Where this work comes from.

An independent ForgeGuard AI server, originally derived from remsky/Kokoro-FastAPI. Licensed Apache-2.0 with required attributions in NOTICE.

• remsky/Kokoro-FastAPIApache-2.0

  The original Dockerized FastAPI wrapper this project builds on.

• Kokoro-82M (hexgrad)Apache-2.0

  Model weights, with the kokoro and misaki libraries.

• StyleTTS2MIT

  Inference code adapted from the StyleTTS2 project.

Status & limitations

Known limitations and roadmap.

• SSML is not supported; only the documented inline pause and IPA pronunciation tokens are parsed.
• Text normalization can occasionally drop or rewrite phrases; it can be disabled per request with normalization_options.
• WAV responses use streaming-sentinel size fields that Python's stdlib wave module misreads; use soundfile or ffprobe for exact durations.
• AMD (ROCm) and Intel images are planned but not yet published.

Roadmap

• Real-time voice endpointsLow-latency incremental synthesis over persistent connections (WebSocket/SSE) with barge-in-friendly cancellation, alongside the existing request/response endpoints.
• More inference backendsAMD (ROCm) and Intel images as hardware becomes available to validate on.

Full history in the changelog; planned work is tracked in the repository roadmap.