Configuration Reference

The bridge is configured entirely from environment variables. The package ships a fully commented .env.example. Only three variables are required.

Required

Env	Meaning
BRIDGE_SECRET	The shared secret from StandIn pairing. Must equal what StandIn holds, or the HMAC upgrade is rejected with 401.
ELEVENLABS_API_KEY	Server-side ElevenLabs key. Mints signed URLs, uploads files, calls TTS. Never sent to the Teams side.
ELEVENLABS_AGENT_ID	The ElevenLabs agent that answers calls.

ElevenLabs

Env	Default	Meaning
EL_HOST	api.elevenlabs.io	Regional pin: api.us.elevenlabs.io, api.eu.residency.elevenlabs.io, api.in.residency.elevenlabs.io, api.sg.residency.elevenlabs.io. Restricted to *.elevenlabs.io.
EL_HOST_ALLOW_ANY	unset	Set to true only to point EL_HOST at a deliberate trusted proxy/test host.
EL_ENVIRONMENT	unset	Environment-specific agent resolution (e.g. a staging agent alongside production).
EL_FIRST_MESSAGE	unset	Localized greeting / spoken AI disclosure (first_message override; must be allowlisted in the agent’s security settings).
EL_AGENT_BRANCH_ID	unset	Pin a specific agent branch per deployment.
EL_TTS_VOICE_ID	unset	Enables the deterministic governor goodbye (exact text via standalone TTS). Without it, the goodbye is delegated to the agent.
EL_TTS_MODEL_ID	eleven_turbo_v2_5	TTS model for the goodbye line.

Caution

ELEVENLABS_API_KEY is sent as xi-api-key to https://{EL_HOST}/.... EL_HOST is allowlisted to *.elevenlabs.io precisely so a mistyped or attacker-influenced host cannot exfiltrate the key. Only set EL_HOST_ALLOW_ANY=true for a proxy you control.

Call governor

Env	Default	Meaning
MAX_CALL_MINUTES	0 (off)	Bridge-side hard cap per call, in minutes (fractional allowed).
GOODBYE_TEXT	a default line	The goodbye the bridge-side governor speaks.
GOODBYE_GRACE_MS	8000	How long to let the goodbye play out before ending the call when its duration is unknown (agent-said fallback). Always hard-bounded.

Vision (path 2)

Env	Default	Meaning
VISION_API_URL	unset	An OpenAI-compatible chat-completions endpoint with image input. Set it to enable path-2 vision (describe-then-answer).
VISION_API_KEY	unset	Bearer key for the vision endpoint (local endpoints may not need one).
VISION_MODEL	unset	Vision model name (required when VISION_API_URL is set).

Ambient vision

Continuous visual awareness: every change to the caller’s screen-share or camera is described and handed to the agent as background context, so it can refer to what is on screen without anyone invoking the look tool.

Env	Default	Meaning
AMBIENT_VISION_ENABLED	false	Opt-in. Each scene change costs one vision-model call, so the default must not spend.
MAX_VISION_PER_MINUTE	30	Sliding 60-second cap on paid vision calls per call, shared by ambient vision and the look tool, and applied whether or not ambient vision is on. 0 = all vision off.
AMBIENT_VISION_REQUIRE_RECORDING	true	Hold ambient pushes back until Teams reports recording.status == "active".

Caution

Ambient vision needs a vision describer - VISION_API_URL + VISION_MODEL, or a VisionDescriber passed to startServer. A text description is the only way this bridge can hand the agent visual context without making it start talking: multimodal_message (path-1 vision) and user_message are both interrupting user turns, so an ambient frame delivered that way would make the agent speak unprompted. With AMBIENT_VISION_ENABLED=true and no describer, the bridge logs one warning per call and stays inactive.

Note

MAX_VISION_PER_MINUTE=0 means off, not unlimited. There is no unlimited setting: a live call always has a spend ceiling.

The cap is not conditional on ambient vision being enabled. Both the ambient pump and the on-demand look tool draw from the same per-call window, so with the default configuration (ambient off, cap 30) an agent that calls look repeatedly is still bounded to 30 vision calls a minute. At 0, look is refused rather than waved through - “off” that leaves a paid path open is not off.

Group-call gate

In a call with two or more humans the agent’s reply audio is withheld until someone addresses it by name, then flows freely for a short follow-up window so the exchange can continue. A 1:1 call is never gated, whatever these are set to.

Env	Default	Meaning
GROUP_CALL_REQUIRE_ADDRESS	true	The gate itself. On by default: it only ever suppresses output, never adds a paid call, and a meeting is exactly where an interjecting bot is harmful. Set false to opt out.
GROUP_CALL_WAKE_PHRASES	assistant	Comma-separated phrases that wake the agent. Matching is case-insensitive and word-boundary aware, so assistantship does not match. Rename this to your agent’s actual name.
GROUP_CALL_FOLLOW_UP_WINDOW_MS	12000	How long after being addressed the agent keeps answering without being named again. The window is refreshed while it is speaking, so a long reply is never cut mid-sentence.

Caution

GROUP_CALL_FOLLOW_UP_WINDOW_MS=0 disables the gate here. The ElevenLabs agent owns turn-taking, so the bridge enforces the gate at the audio egress, where there is no transcript and the follow-up window is the only thing that can open it - a zero window could never open and would mute the agent in every meeting. Every fail-safe in the gate leans the same way: a gate that cannot be opened is treated as disabled, never as permanent silence. Use GROUP_CALL_REQUIRE_ADDRESS=false to turn it off deliberately.

Note

The gate is a behavioural backstop, not a cost control: the agent has already generated the reply by the time its audio is withheld. The cost lever is the etiquette line the bridge sends alongside the participant count, which names the wake phrases and asks the agent to stay quiet unless addressed. The governor goodbye is never withheld - it is the compliance line the call has to end on.

Server and transport

Env	Default	Meaning
PORT	9442	TCP port the bridge listens on.
BIND	0.0.0.0	Bind address.
HMAC_FRESHNESS_MS	60000	Allowed clock skew for the HMAC timestamp.
MAX_CONNECTIONS	0 (= 64)	Max concurrent connections.
MAX_CONNECTIONS_PER_IP	0 (= 8)	Max concurrent connections from one remote IP.
PRE_START_TIMEOUT_MS	0 (= 10000)	Drop a connection that authenticates but never sends session.start.
WORKER_IDLE_TIMEOUT_MS	0 (= 90000)	Dead-peer window: end the call after this long without any worker message (the worker heartbeats every 30 s). Frees the call id for reconnect and closes the billed ElevenLabs conversation.
STALE_CALL_REAPER_SECONDS	120	End a connected call that never went live (the ElevenLabs session never opened) with reason no-answer. Unlike the pre-start timeout this also covers a call that did send session.start and then wedged, which nothing else ends while the worker keeps heartbeating. 0 disables it. On by default because it spends nothing - it makes no provider call, it only frees local resources.
LOG_TRANSCRIPTS	false	Log ElevenLabs transcripts (still gated on Teams recording.status == "active").

The bridge also exposes GET /metrics (Prometheus text format, no auth): calls total/active, call seconds, upgrade rejections by cause, frames relayed each way, backpressure drops, and ElevenLabs connect failures. Like /healthz it is served on the same port - keep the port private to your network or scrape through your ingress. | LOG_LEVEL | info | debug | info | warn | error. An invalid value falls back to info. |

Note

Numeric variables fail loud: MAX_CALL_MINUTES=abc stops startup with a clear error rather than silently disabling the governor, and a non-numeric PORT stops with a clear message instead of an opaque listen error.

Caution

BIND=0.0.0.0 exposes the bridge (and therefore the shared-secret-gated upgrade) on every interface. Bind to loopback and put a TLS-terminating reverse proxy in front, or restrict access at the network layer.

The audio format is fixed at pcm_16000 by design (the no-transcode contract) and is not configurable. The bridge validates the agent’s declared format at call start and ends the call on a mismatch.