Operate and troubleshoot PrismVox

Diagnose the failing stage: SIP registration, audio transport, transcription, model response or synthesis. Changing every setting at once makes an intermittent phone problem harder to isolate.

Status and logs

docker compose ps
docker compose logs --tail=100 agent ui
docker compose logs --tail=100 asterisk embeddings

Keep DEBUG and LOG_SENSITIVE_DATA false for ordinary operation. Read diagnostic logs privately and redact keys, numbers, transcripts and private hosts before opening an issue. Record the version, provider/model IDs, symptom and reproduction steps.

The trunk does not register

• Verify authentication username/password, domain, registrar and source matching with the provider. The SIP username may differ from the public number.
• Check UDP/TLS transport, remote port and certificate trust. For a private CA, mount the correct bundle rather than disabling verification.
• If .env changes appear ignored, inspect the saved SIP form: the existing trunk is stored persistently and is not overwritten at every startup.

Calls connect but audio is silent

Validate RTP/NAT/firewall requirements and the provider’s codecs. The supplied host publication is UDP 10000–10100 for RTP and UDP 5060 for signaling. Keep the agent on a single Docker network; attaching a second can make its RTP hostname resolve to the wrong interface. Distinguish inbound recognition failure from outbound playback failure.

Speech or model errors

A 401/403 usually requires checking credential permissions and provider URL. A missing voice/model requires the exact ID allowed by the account. For external speech, verify the actual API contract rather than the model brand: STT uses multipart file and returns JSON text; TTS accepts input/model/optional voice and returns WAV.

STT_PROVIDER=openai
STT_URL=http://host.docker.internal:8000/v1
STT_MODEL=your-transcription-model
TTS_PROVIDER=openai
TTS_URL=http://host.docker.internal:8880/v1
TTS_MODEL=your-speech-model
TTS_VOICE=your-voice-id
SPEECH_SERVICE_API_KEY=

This example requires separately deployed compatible servers. You can also change just one provider and retain ElevenLabs for the other. Save the equivalent Speech providers form if an existing saved configuration overrides .env.

Latency and voice consistency

Measure where the delay occurs: end-of-speech detection, model time-to-first-text, synthesis or network/media delivery. Use a compact tool-capable conversation model and concise persona. Tune stability and interruption thresholds with a real handset; avoid choosing a setting solely from a text-chat test. More knowledge chunks and longer answers also increase work.

Back up data and the encryption key together

Preserve .env, pgdata, secrets and asterisk_dynamic. The secrets volume contains the key required to decrypt stored SIP and provider credentials: the database alone is not enough. ui_certs contains console certificates and sounds can contain generated audio. Treat all backups as private data and test restoration on a separate deployment.

Upgrade a running installation

Wait for calls and outbound work to finish, back up the persistent state, keep the same Compose project name, then pull and rebuild. A repository update alone does not replace a running image. Never use down -v as an update command: it deletes volumes.

git pull --ff-only
docker compose up -d --build
docker compose ps

Older PrismConnect installs must first select ElevenLabs or external speech services before removing the old bundled engines. Keep the old volumes until replacement calls work, and keep your existing project name and encryption-key volume.