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 |
Runtime Modes
Remote
Use remote packages by default.
Examples:
@charivo/llm/remote@charivo/tts/remote@charivo/stt/remote@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/tts/openai@charivo/stt/openai@charivo/realtime/openai-agents@charivo/realtime/openai
The browser-direct caveat above is about the browser client, player, or
transcriber factory (createOpenAILLMClient, createOpenClawLLMClient,
createOpenAITTSPlayer, createOpenAISTTTranscriber) on the first four
subpaths. Those same subpaths double as the home of the matching server-side
provider factory (createOpenAILLMProvider, createOpenClawLLMProvider,
createOpenAITTSProvider, createOpenAISTTProvider) — 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 or @charivo/server/openclaw
Text-to-speech with lip-sync events
@charivo/core
@charivo/tts
@charivo/tts/remote
@charivo/server/openai
Speech-to-text from the microphone
@charivo/core
@charivo/stt
@charivo/stt/remote
@charivo/server/openai
Realtime voice sessions
@charivo/core
@charivo/realtime
@charivo/realtime/remote
@charivo/server/openai
Live2D rendering
@charivo/render
@charivo/render-live2d
Rules Of Thumb
- For user-facing browser apps, start with remote packages.
- For demos and local harnesses, browser-direct packages are acceptable.
- For the fewest moving parts in speech features, browser-native TTS/STT may be enough.
- For realtime today, prefer
@charivo/realtime/remote, which can resolve the OpenAI Agents WebRTC adapter by default.