Deploy and Host Piper TTS on Railway

Built for an LLM agent to deploy and use. There is nothing to fill in: the API key is generated at deploy time, every speech request needs it, a voice is already installed, and the contract below lists every URL and variable name with one script that checks health, auth and a real synthesis.

Piper is a fast, local neural text-to-speech engine that runs on CPU with no GPU and no external API. This template runs Piper 1.8 behind a small server that speaks the OpenAI speech API, so any client that can call /v1/audio/speech can use it by changing the base URL and the key.

About Hosting Piper TTS

This template runs one service, built from the public wrapper bon5co/piper-railway (piper-tts 1.8.0, pinned by digest), with the volume at /data. Piper's own HTTP server has no authentication, so a public URL would let anyone use your CPU. Here every request under /v1/ needs Authorization: Bearer plus the value of API_KEY; anything else gets 401. Only /healthz is open, and it returns 200 once the default voice is loaded.

The image ships one voice, en_US-ljspeech-high (trained on the public-domain LJ Speech dataset), and copies it onto the volume at first boot. Add more by setting EXTRA_VOICES to a comma separated list of Piper voice names such as en_GB-alan-medium,de_DE-thorsten-medium and redeploying, or by copying a voice's .onnx and .onnx.json files into /data/voices. Check each added voice's licence: some datasets are non-commercial. ONNX Runtime thread pools are sized from the container's CPU quota, not the host's core count, so synthesis does not slow down on a shared host. Output formats are wav, pcm, mp3, opus, aac and flac.

Agent contract

Public URL: https://RAILWAY_PUBLIC_DOMAIN, on the piper service (set PIPER_URL to it, no trailing slash)
Private URL: http://piper.railway.internal:8080 (key required)
Credentials: the key is in API_KEY (on the piper service)
Auth: send Authorization: Bearer API_KEY on every /v1/ request; a missing or wrong key gets 401
Health: GET /healthz returns 200 with no credentials once the default voice is loaded

# run with PIPER_URL and API_KEY (piper service); needs curl
curl -s -o /dev/null -w 'health %{http_code}\n' "$PIPER_URL/healthz"
curl -s -o /dev/null -w 'anonymous %{http_code}\n' "$PIPER_URL/v1/voices"
curl -s -o /dev/null -w 'wrong key %{http_code}\n' -H 'Authorization: Bearer wrong' "$PIPER_URL/v1/voices"
curl -s -H "Authorization: Bearer $API_KEY" "$PIPER_URL/v1/voices"; echo
curl -s -o speech.wav -w 'speech %{http_code} %{size_download} bytes\n' -X POST "$PIPER_URL/v1/audio/speech" \
  -H "Authorization: Bearer $API_KEY" -H 'Content-Type: application/json' \
  -d '{"input":"Hello from Piper on Railway.","response_format":"wav"}'
head -c 4 speech.wav; echo

A fresh deploy prints health 200, anonymous 401, wrong key 401, the voice list with en_US-ljspeech-high, speech 200 with a size in the tens of kilobytes, and RIFF. The voice field is optional: a name that is not installed (including OpenAI names such as alloy) falls back to the default voice. speed takes 0.25 to 4.0.

Why Deploy Piper TTS on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Piper TTS on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

Agent-ready - generated key, a contract block and one working script; no setup step.
Closed by default - Piper's own server has no auth; here every speech call needs the key.
OpenAI-compatible - point an existing speech client at the URL and key, no code change.
Light on CPU - a voice runs in about 250 MB of memory and needs no GPU.
State survives redeploys - voices live on the volume, and the key stays the same after every redeploy.

Common Use Cases

Voice for AI agents - give an agent a private speech endpoint that returns audio from text with one authenticated call.
App narration and notifications - read articles, alerts or lessons aloud without paying per character to a cloud TTS.
Self-hosted OpenAI TTS replacement - keep text on your own infrastructure and cut the per-request bill.

Dependencies for Piper TTS Hosting

A volume at /data (included in this template).

Deployment Dependencies

OHF-Voice/piper1-gpl - Piper, upstream project (GPL-3.0-or-later)
rhasspy/piper-voices - voice models and their licences
bon5co/piper-railway - the wrapper image this template deploys