PrismVox environment reference

COMPOSE_PROJECT_NAME

Example / default

prismvox

Purpose

Docker Compose project identity and volume prefix.

How to use it

Keep it unchanged on upgrades. A new name creates a different deployment with different volumes; it does not rename or migrate your database.

COMPOSE_FILE

Example / default

docker-compose.yml

Purpose

Compose files used by commands in this directory.

How to use it

Use the base file alone for ElevenLabs or external speech APIs. On Linux append :docker-compose.llm-local.yml only when adding the optional local language model. Old bundled STT/TTS overlays are removed.

ARI_USER

Example / default

phoneagent

Purpose

Asterisk REST Interface account used by the agent and console.

How to use it

Keep the account consistent across Asterisk, agent and UI. It is not your SIP trunk identity or the web-console login.

ARI_PASS

Example / default

(generate; replace change_me_ari)

Purpose

Password for the internal Asterisk API.

How to use it

Generate a unique value before startup. Compose passes it to each component that controls calls. Do not publish the Asterisk ARI port to the Internet.

DB_PASS

Example / default

(generate; replace change_me_db)

Purpose

PostgreSQL account password for phoneagent.

How to use it

Set before creating the database volume. On an existing volume, changing the environment alone does not change the PostgreSQL password: rotate the database account and clients together.

UI_USER

Example / default

admin

Purpose

Administrative console Basic-auth username.

How to use it

Choose an operator login. Use this same username as VOX_USER in Prism when connecting the projects.

UI_PASSWORD

Example / default

(generate; replace change_me_ui)

Purpose

Administrative console and API password.

How to use it

Keep authentication enabled even on a trusted network. Empty removes this Basic-auth protection. When docked, Prism uses this password to proxy the administrative API.

AGENT_API_KEY

Example / default

(empty)

Purpose

Separate Bearer token for agent-chat and OpenAI-compatible chat endpoints.

How to use it

Set it when another application calls these conversational APIs. It is not the console password or the ElevenLabs key, and does not grant administrative API access.

UI_BIND

Example / default

127.0.0.1

Purpose

Host interface on which console ports 7860 and 7861 are published.

How to use it

Keep loopback for local use or an on-host reverse proxy. To use another bind address, restrict network access and configure trusted HTTPS; 0.0.0.0 listens on every IPv4 interface.

UI_TLS_SAN

Example / default

(empty)

Purpose

Optional extra subject alternative name in the console’s self-signed certificate.

How to use it

Use a SAN such as IP:192.0.2.20 for a lab address. This does not create a publicly trusted certificate. Browser microphone access requires a secure context such as localhost or trusted HTTPS.

SIP_REGISTRAR

Example / default

sbc.example.com

Purpose

Registrar/SBC hostname supplied by your SIP provider or PBX.

How to use it

Use the provider’s actual hostname. Bootstrap values seed the saved trunk on the first startup; subsequent trunk changes belong in Configuration → SIP / Telephony.

SIP_REGISTRAR_IP

Example / default

192.0.2.10

Purpose

Operator signaling IP used for the Compose SIP_DOMAIN host mapping and default inbound SIP matching.

How to use it

Replace the documentation address with the address supplied by your provider. Check DNS/IP changes with the provider instead of assuming the example can carry calls.

SIP_REGISTRAR_MATCH

Example / default

192.0.2.10

Purpose

Allowed source address or match expression for inbound SIP identification.

How to use it

Default follows SIP_REGISTRAR_IP. Match the provider’s signaling sources; do not broaden to the whole Internet just to make registration work.

SIP_DOMAIN

Example / default

example.com

Purpose

SIP domain used in signaling and contact addresses.

How to use it

Use the SIP domain given with the account, which may differ from your public website domain or registrar hostname. The shipped Compose also maps it to SIP_REGISTRAR_IP.

SIP_USERNAME

Example / default

phoneagent

Purpose

Authentication identity of the SIP account/trunk.

How to use it

Copy the authentication username, which may differ from the public telephone number. It is distinct from UI_USER and ARI_USER.

SIP_PASSWORD

Example / default

(empty)

Purpose

Secret used to authenticate the SIP trunk.

How to use it

Obtain it from your SIP provider. Saved SIP credentials are encrypted; editing .env after initialization does not replace the saved trunk. Use the SIP form for later changes.

SIP_TRANSPORT_MODE

Example / default

tls

Purpose

SIP signaling transport, tls or udp.

How to use it

Match the transport supported by your provider. The bundled TLS profile also requests SDES-SRTP media encryption; UDP uses plain RTP. Both must match provider support and firewall/NAT settings.

SIP_TLS_PORT

Example / default

5061

Purpose

Remote TLS signaling port.

How to use it

Use the port provided by the registrar when SIP_TRANSPORT_MODE=tls. Changing it does not change Compose host port publications.

SIP_UDP_PORT

Example / default

5060

Purpose

Remote UDP signaling port.

How to use it

Used for UDP transport. The bundled stack publishes UDP 5060 and RTP UDP 10000–10100; adapt firewall/NAT rules to your own trunk.

SIP_TLS_VERIFY_SERVER

Example / default

yes

Purpose

Certificate verification for the SIP TLS peer.

How to use it

Keep yes with a valid provider certificate. For a private CA, mount its certificate and configure SIP_TLS_CA_FILE rather than disabling verification.

SIP_TLS_CA_FILE

Example / default

/etc/ssl/certs/ca-certificates.crt

Purpose

CA bundle path inside the Asterisk container.

How to use it

The default trusts the container’s public CA bundle. A custom host file needs an explicit read-only Compose mount at the selected container path. A host path alone is not visible inside Docker.

OPENAI_BASE_URL

Example / default

http://host.docker.internal:4000/v1

Purpose

OpenAI-compatible gateway root for the local conversation loop.

How to use it

Include /v1 and make the endpoint reachable from the containers. Use a tool-calling model. Standard/on-call URL overrides can be configured later in Agent settings.

OPENAI_MODEL

Example / default

your-model-id

Purpose

Initial model for both conversation tiers.

How to use it

Replace with an exact served model ID. This seeds the standard/on-call settings only when absent; existing saved tier choices remain.

OPENAI_API_KEY

Example / default

(empty)

Purpose

Credential for the default language-model gateway.

How to use it

Leave empty only for an endpoint that requires no key. The gateway credential is not forwarded to a different per-tier endpoint; configure those endpoints accordingly.

PRISM_URL

Example / default

(empty)

Purpose

Internal Prism server root for docked operation.

How to use it

For a shared network use http://prism-server:8080. Requires a matching PRISM_TOKEN and a network path in both directions. Empty leaves PrismVox standalone.

PRISM_TOKEN

Example / default

(empty)

Purpose

Prism service credential used for caller lookup and voice sessions.

How to use it

Copy the service token from the connected Prism deployment. This is privileged integration material, not a tester’s login password. Keep it private.

PRISM_PUBLIC_URL

Example / default

https://prism.example.com

Purpose

Browser-accessible Prism address when the console is docked.

How to use it

Use the actual public or local browser URL. The Docker-only name prism-server usually cannot resolve in a user’s browser; it belongs in PRISM_URL, not here.

STT_PROVIDER

Example / default

elevenlabs

Purpose

Speech recognition provider: elevenlabs, openai or service.

How to use it

ElevenLabs uses the direct streaming integration. openai targets an externally hosted compatible API; service keeps the legacy /transcribe contract. No speech engine is installed by this setting.

TTS_PROVIDER

Example / default

elevenlabs

Purpose

Speech synthesis provider, independent of STT_PROVIDER.

How to use it

Use elevenlabs, openai or service. You can mix external recognition with ElevenLabs synthesis. Saved Speech providers settings take precedence and apply to new calls.

ELEVENLABS_API_KEY

Example / default

(empty)

Purpose

API key for ElevenLabs recognition and synthesis.

How to use it

Enter your own key here or in Speech providers. Use a key with the permissions required for your chosen models and voices. Audio is sent to this external provider and usage may be billed.

ELEVENLABS_VOICE_ID

Example / default

(empty)

Purpose

ElevenLabs voice identifier, not its display name.

How to use it

Choose an available voice after Connect in Speech providers or copy its exact ID. Without a valid key and voice, ElevenLabs synthesis is not ready.

ELEVENLABS_STT_MODEL

Example / default

scribe_v2_realtime

Purpose

ElevenLabs speech recognition model ID.

How to use it

Keep the realtime model for the streaming path. Select a different supported recognition model through Speech providers if your account and use case require it.

ELEVENLABS_TTS_MODEL

Example / default

eleven_flash_v2_5

Purpose

ElevenLabs speech synthesis model ID.

How to use it

Use a model available to your account and suitable for the language. Latency and voice behavior vary by model; the preview sends a real synthesis request.

ELEVENLABS_LANGUAGE

Example / default

fr

Purpose

Speech language code.

How to use it

Use fr for French or en for English, for example. Align the greeting, persona, fixed phrases and pronunciation settings with the same language. The console language does not change call language.

ELEVENLABS_STABILITY

Example / default

(empty)

Purpose

Optional synthesis stability between 0 and 1.

How to use it

Empty keeps provider defaults. Larger values generally seek steadier delivery; tune with short previews and real calls rather than assuming one value suits all voices.

ELEVENLABS_BASE_URL

Example / default

https://api.elevenlabs.io/v1

Purpose

ElevenLabs API root.

How to use it

Keep the official URL for normal use. Only change for an explicit trusted compatible proxy; never send a production key to an untrusted endpoint.

STT_URL

Example / default

http://host.docker.internal:8000/v1

Purpose

External recognition API root.

How to use it

Used with STT_PROVIDER=openai; PrismVox adds /audio/transcriptions. With service, it uses the legacy /transcribe route. Ignored by direct ElevenLabs recognition.

STT_MODEL

Example / default

(empty)

Purpose

Optional model ID sent to the external transcription API.

How to use it

Use the ID expected by your own server. No Whisper-specific model or server is assumed; compatibility depends on the actual multipart transcription contract.

TTS_URL

Example / default

http://host.docker.internal:8880/v1

Purpose

External synthesis API root.

How to use it

Used with TTS_PROVIDER=openai; PrismVox adds /audio/speech and requests WAV. For service, configure the legacy synthesis URL, normally ending in /synthesize.

TTS_MODEL

Example / default

(empty)

Purpose

Model ID sent to the external synthesis API.

How to use it

Use your server’s model identifier. It is not an ElevenLabs model setting and does not download an engine.

TTS_VOICE

Example / default

(empty)

Purpose

Optional voice ID sent to an external synthesis API.

How to use it

Use a voice installed on that server. Manage external voice uploads/deletion on the server itself; ElevenLabs voices are selected separately.

SPEECH_SERVICE_API_KEY

Example / default

(empty)

Purpose

Optional Bearer credential for external OpenAI-compatible speech APIs.

How to use it

Independent of ELEVENLABS_API_KEY. The external STT and TTS connections share this credential; leave empty only if those servers allow it.

WHISPER_HOTWORDS

Example / default

(empty)

Purpose

Bootstrap hints for recognition of names and domain vocabulary.

How to use it

Historical variable name; it does not require Whisper. Edit the vocabulary in Dictionary after first startup. Whether hints apply depends on the selected recognition API.

TTS_SPELL_WORDS

Example / default

(empty)

Purpose

Bootstrap words/acronyms to spell letter by letter.

How to use it

Use comma-separated entries, then maintain them in Dictionary. Keep the list focused on terms that the chosen voice actually mispronounces.

TTS_SPELL_EXCEPTIONS

Example / default

OK

Purpose

Terms that should not be automatically spelled.

How to use it

Comma-separated exceptions to acronym handling. Keep ordinary spoken abbreviations natural; saved dictionary values override bootstrap values.

TTS_SPELL_ACRONYMS

Example / default

true

Purpose

Enables automatic acronym pronunciation handling.

How to use it

Set false if automatic spelling harms your chosen voice/language. Review the pronunciation alongside the dictionary and provider settings.

EMBEDDING_MODEL

Example / default

paraphrase-multilingual-MiniLM-L12-v2

Purpose

Sentence-transformers model used by the bundled CPU embedding service.

How to use it

The current database stores 384-dimensional vectors. Keep a compatible 384-dimensional model; an arbitrary embedding model is not a drop-in replacement. Changing models also requires reindexing documents.

RAG_TOP_K

Example / default

5

Purpose

Maximum retrieved document chunks per knowledge search.

How to use it

Increase only if useful information is consistently missed. More chunks enlarge the model input and can add latency; good collections and source documents matter first.

BARGEIN_MS

Example / default

2000

Purpose

Sustained speech threshold, in milliseconds, for interrupting playback.

How to use it

Lower can interrupt sooner but is more vulnerable to echo/noise. Test with your actual handset and network, including longer spoken replies.

LOG_SENSITIVE_DATA

Example / default

false

Purpose

Enables sensitive call-data logging when explicitly set true.

How to use it

Keep false for ordinary operation. Debugging with sensitive data needs restricted log access, a limited retention period and redaction before sharing.

DEBUG

Example / default

false

Purpose

Additional diagnostic logging.

How to use it

Enable temporarily for a reproducible problem, inspect logs privately and disable afterwards. It is separate from LOG_SENSITIVE_DATA.

FAST_LLM_MODEL_DIR

Example / default

./.dev/models/qwen3.5-9b

Purpose

Host folder mounted read-only into the optional model service.

How to use it

Used only by docker-compose.llm-local.yml. Download the GGUF file separately and ensure Docker can read this folder; the overlay does not download it.

FAST_LLM_MODEL_FILE

Example / default

Qwen3.5-9B-Q8_0.gguf

Purpose

GGUF filename inside the configured model folder.

How to use it

Match the downloaded file exactly. The supplied overlay requires an NVIDIA GPU/runtime and sufficient VRAM; its context size and sampling are defined in the overlay.

FAST_LLM_MODEL_NAME

Example / default

qwen3.5-9b

Purpose

Served alias exposed by the optional local API.

How to use it

Select this alias with http://fast-llm:8080/v1 in Agent model settings. The alias is separate from the physical GGUF filename.

FAST_LLM_PORT

Example / default

18120

Purpose

Loopback host port for the optional local model’s diagnostic API.

How to use it

The call agent uses port 8080 on the Docker network. Change the host port to avoid a conflict; this does not change the internal model URL.

BARGEIN_VAD_MODE

Voice-activity detector aggressiveness for interrupting playback: 0–3. Higher values reject more noise. This is separate from BARGEIN_MS; change only after testing speech and acoustic echo on a real handset.

Service: agent · Default: 3

SECRET_KEY_PATH

Path to the persistent shared encryption key. Both services must read the same key; the standard secrets volume supplies it. Do not replace the key during an upgrade or restore only the database.

Service: ui and agent · Default: /var/lib/prismvox/secret.key

SIP_CALLERID_NAME

Optional first-start value for the outbound display name. The base Compose does not forward it; use Display name (From) in the SIP form for normal configuration. It does not change authentication identity.

Service: ui · Default: Empty

SIP_TRANSFER_METHOD

Optional first-start choice, bridge or refer, for blind transfer. Use the SIP form normally; attended transfers remain bridged. Adding this variable to .env alone does not forward it in the supplied Compose.

Service: ui · Default: bridge

ARI_URL

Internal administrative ARI address used by the console; the agent has its own ARI_HOST/ARI_PORT wiring. Change only when restructuring the service network.

Service: ui · Default: http://asterisk:8088

ASTERISK_DYNAMIC_DIR

Container path shared with Asterisk for the generated SIP configuration. An override must preserve the shared volume and its permissions; it is not a new SIP line.

Service: ui · Default: /asterisk-dynamic

EMBEDDINGS_URL

Internal URL of the embedding service. Both ingestion and search must reach a compatible service with the same vector dimension.

Service: agent and ui · Default: http://embeddings:8002

DATABASE_URL

Internal PostgreSQL connection built from DB_PASS and the database service. Keep both services on the same database. This is not a separate user account or an AI-provider URL.

Service: agent and ui · Default: Compose-managed

LLM_MODEL

Legacy console-side model fallback when OPENAI_MODEL is absent. Prefer OPENAI_MODEL and the saved standard/on-call model settings so the console and call agent agree.

Service: ui · Default: Compatibility fallback