Choose an AngeVoice deployment
Choose the most stable profile for the hardware. Do not use Legacy GPU only because the host has a GPU.
Deployment comparison
| Profile | Best for | Advantages | Watch for |
|---|---|---|---|
| CPU | NAS systems, hosts without NVIDIA GPUs, initial validation | Broad compatibility and simpler troubleshooting | Cloning models may be slower |
| Standard GPU | Regular NVIDIA x86_64 hosts | Kokoro, MOSS and ZipVoice can prefer CUDA | The host driver and container GPU runtime must work |
| Legacy GPU | Older driver stacks where the standard image cannot start | More conservative compatibility stack | Not a performance upgrade; some models use CPU by default |
Start manually
# CPU, port 8100
cd docker/cpu && docker compose up -d
# Standard NVIDIA GPU, port 8101
cd docker/gpu && docker compose up -d
# Compatibility profile, port 8102
cd docker/legacy-gpu && docker compose up -d
Confirm that the GPU is actually used
nvidia-smi
curl http://127.0.0.1:8101/v1/models/current
docker logs --tail 200 angevoice-gpu
The status response reports the requested provider, actual provider and fallback reason. requested=cuda with actual=cpu usually means the service is usable but that model fell back to CPU.
Persistent data
models/ Model files and download cache
prompts/ Voice Profiles and reference audio
outputs/ Generated audio
credentials/ Administrator hashes and API key
config/ Runtime configuration
logs/ Logs and diagnostic bundles
Mount the same directories when switching between CPU, GPU and Legacy GPU.
When to switch profiles
| Situation | Recommendation |
|---|---|
| The standard GPU image starts and synthesizes correctly | Keep the standard GPU profile |
| CUDA or cuDNN prevents the standard image from starting | Update the image and driver first; try Legacy GPU only if the issue remains |
| GPU memory is insufficient | Load one model at a time or let cloning models fall back to CPU |
| You only need to validate the API | Start with CPU, then migrate after the full path works |