Voice

Use voice to ask about tasks, answer an agent's question, and steer work away from the keyboard. caic supplies task-specific tools and context; Go Mode supplies the shared voice interface and gateway. Voice is available in the web app and the Go Mode Android shell.

Start a session

Press F4 in the web app to start or stop voice mode, including while the composer has focus. Say “hang up”, “end call”, or “stop voice mode” to end the session.

caic announces every task transition to waiting, asking, failed, or crashed immediately, before answering anything else, even when no one asked for a status update. For a failure, it reads the recorded error instead of an unknown cause.

Voice numbers active tasks before settled tasks. Check the visible list when a number could be ambiguous. The voice interface's supported speech modes and language settings depend on the client platform; see the Go Mode voice guide.

Embedded gateway

Set GEMINI_API_KEY and leave the gateway URL empty to host the gateway inside caic:

[core.env]
GEMINI_API_KEY = "AIza..."

Without a key or gateway URL, voice is disabled. The key can also come from the server process environment. The gateway's default backend uses Gemini Live, so audio is sent to that provider.

Standalone gateway

A standalone gateway lets you run voice separately from caic. Configure a fixed service URL and instance ID, and choose its session credential mode. Before using OAuth credentials, configure a supported dashboard login provider so caic can issue and verify authenticated sessions. Then add:

[server]
external_url = "https://caic.example.com"

[voice-gateway]
url = "https://voice.example.com"
instance_id = "caic-main"
token_mode = "oauth"

Configure the gateway to trust service caic with issuer https://caic.example.com and oauth = true. The gateway discovers caic's verification keys through authorization-server metadata. caic issues short-lived voice-only credentials rather than sharing provider or forge tokens.

The default token_mode = "scoped" uses a separate Ed25519 signing key instead. Generate it with:

openssl genpkey -algorithm Ed25519 -out ~/.config/caic/voice-signing-key.pem

Change token_mode to "scoped" and set signing_private_key_pem = "voice-signing-key.pem" alongside instance_id, and configure the gateway's trusted issuer with the public key printed by caic at startup. See Go Mode voice for gateway installation and trust configuration.

Local models

To use local speech recognition, an LLM, and speech synthesis, choose the local stack:

[voice-gateway.config]
backend = "local-stack"

The local stack runs half-duplex: you speak and listen in turns. It can manage models or connect to local model servers. Embedded activation currently still requires GEMINI_API_KEY to be present, but this backend does not consume that key or send audio to Gemini.

Use the caic gateway config template for embedded settings, and the Go Mode voice guide for local runtime requirements. Avoid copying standalone gateway settings into caic's embedded HTTP configuration.

Network access

WebRTC audio needs a reachable UDP port. The default chooses an ephemeral port; the gateway can request a temporary UPnP mapping on a compatible router. To create a stable firewall rule, set a fixed port:

[voice-gateway.config.server]
webrtc_udp_port = 3479

Allow that UDP port through your firewall. Signaling also needs access to the gateway's HTTP endpoint. A working HTTPS page does not prove that WebRTC UDP traffic can reach the gateway.

See Configuration for caic's gateway fields and Security for the trust boundary.