VoiceThere

Runner settings

Runner settings control how VoiceThere provisions and runs your uploaded agent on cloud session workers: voice vs data channels, warm pools, shared vs per-session agent children, scale-down when idle, and optional debug logging. They are distinct from session idle timeout (per-peer WebRTC disconnect).

Where to configure

  • Dashboard: Project overview → Runner settings.
  • CLI: voicethere projects settings list and voicethere projects settings set <key> <value>
  • API: PATCH /projects/:projectId/runner-settings — see Control plane API.

Changes are stored on the project immediately but apply to live traffic only after you Deploy to cloud (runner configuration is baked at deploy time).

Runner mode

Key mode — how the session worker exposes media paths:

  • voice — inbound/outbound audio for STT/TTS voice agents (default).
  • data — data channels only (no voice pipeline).
  • voice+data — both voice and data channels active.

Legacy data_only=true is an alias for mode=data; prefer mode.

Warm pool

warm_pool_enabled keeps a number of runner instances running continuously so new sessions start faster. Availability depends on your subscription tier. When disabled, runners scale from zero on demand.

Shared agent child

shared_child_per_session (default false for voice):

  • false — each session gets its own sandboxed agent child (isolated voice sessions).
  • true — one agent child serves every session on the same runner pod (multiplayer / shared state). See Agent crash policy for crash scope.

Idle scale-down

idle_scale_down_seconds (default 300) — after this many seconds with no active sessions on a runner, the deployment scales the runner pool down. This is pool-level idle, not per-peer disconnect (see Session idle timeout). Minimum 60 seconds; maximum 86,400.

Agent child IPC debug

agent_child_ipc_debug enables verbose parent↔child IPC logs on runner instances. May require support to enable on your plan. Takes effect after redeploy. Use for short-lived troubleshooting — not for production steady state.

Other runner keys

CLI examples

# List effective runner settings
voicethere projects settings list

# Data-only multiplayer project
voicethere projects settings set mode data
voicethere projects settings set shared_child_per_session true
voicethere deploy --wait

# Enable warm pool (when tier allows)
voicethere projects settings set warm_pool_enabled true
voicethere deploy --wait

# Scale runners down after 10 minutes idle
voicethere projects settings set idle_scale_down_seconds 600
voicethere deploy --wait

# Short-lived IPC debug (redeploy, then disable when done)
voicethere projects settings set agent_child_ipc_debug true
voicethere deploy --wait

Related

← All documentation