Choosing Packages
Charivo supports three runtime styles: remote, browser-direct, and browser-native. This page helps you choose the right one for each subsystem.
Default Choice
For most browser apps, use:
@charivo/core- the relevant modality root packages
- remote browser runtime packages
- server provider packages behind your API routes
Choose browser-direct or browser-native packages only when you explicitly want their tradeoffs.
Quick Decision Table
| Need | Pick | Why |
|---|---|---|
| Production browser app | Remote browser package + server provider package | Keeps credentials on the server |
| Local development against vendor APIs | Browser-direct vendor package | Faster setup, but credentials bundle into shipped JavaScript |
| Zero-server browser speech | Browser-native web package | No backend needed, but browser support varies |
| Deterministic demo or UI work | Stub client where available | No model dependency |
| Realtime voice today | @charivo/realtime/remote | Resolves the OpenAI Agents WebRTC or Gemini Live WebSocket adapter from the session's provider/transport |
Runtime Modes
Remote
Use remote packages by default.
Examples:
@charivo/llm/remote@charivo/tts/remote@charivo/stt/remote@charivo/stt/openai-realtime— streaming transcription over WebRTC; it holds no credential itself and calls an app-supplied bootstrap that runs on your server (see STT for its press-to-start/stop constraints)@charivo/stt/gemini-live— streaming transcription over the Gemini Live websocket; it ships no key-bearing helper either and calls an app-supplied bootstrap that mints the session token on your server, but the browser then holds that short-lived token for the life of one recording (see STT for that and its press-to-start/stop constraints)@charivo/realtime/remote
Choose this path when:
- the app runs in the browser
- you want credentials to stay on the server
- you already own API routes or server functions
Browser-Direct
Use browser-direct vendor packages for development, demos, trusted environments, or quick provider checks that intentionally bypass your server. These packages expose provider credentials to the browser; production browser apps should prefer the remote/server-mediated path.
Examples:
@charivo/llm/openai@charivo/llm/openclaw@charivo/llm/gemini@charivo/tts/openai@charivo/tts/gemini@charivo/stt/openai@charivo/stt/gemini@charivo/realtime/openai-agents@charivo/realtime/gemini
@charivo/realtime/openai is NOT in this list: the legacy low-level transport
takes only apiEndpoint or sessionBootstrap, so it always goes through your
server and never holds a provider credential. It is a legacy/debugging path,
not a credential-exposing one.
The browser-direct caveat above is about the browser client, player, or
transcriber factory (createOpenAILLMClient, createOpenClawLLMClient,
createGeminiLLMClient, createOpenAITTSPlayer, createGeminiTTSPlayer,
createOpenAISTTTranscriber, createGeminiSTTTranscriber) on the first seven
subpaths. Those same subpaths double as the home of the matching server-side
provider factory (createOpenAILLMProvider, createOpenClawLLMProvider,
createGeminiLLMProvider, createOpenAITTSProvider,
createGeminiTTSProvider, createOpenAISTTProvider, createGeminiSTTProvider)
— the provider is meant to run on the server and refuses to run in a browser
unless you pass dangerouslyAllowBrowser: true.
Choose this path when:
- you want the shortest local setup
- you are testing provider behavior directly
- bundling provider credentials into shipped JavaScript is acceptable
Browser-Native
Use browser-native speech packages when you want no backend for TTS or STT.
Examples:
@charivo/tts/web@charivo/stt/web
Choose this path when:
- you want a prototype or zero-server feature
- browser support differences are acceptable
- provider-level model control is not required
Common Stacks
Text chat with server routes
@charivo/core
@charivo/llm
@charivo/llm/remote
@charivo/server/openai, @charivo/server/openclaw, or @charivo/server/gemini
Text-to-speech with lip-sync events
@charivo/core
@charivo/tts
@charivo/tts/remote
@charivo/server/openai or @charivo/server/gemini
Speech-to-text from the microphone
@charivo/core
@charivo/stt
@charivo/stt/remote
@charivo/server/openai or @charivo/server/gemini
Realtime voice sessions
@charivo/core
@charivo/realtime
@charivo/realtime/remote
@charivo/server/openai or @charivo/server/gemini
Live2D rendering
@charivo/render
@charivo/render-live2d