Practical overview
When it fits
Use Utsuwa when you want companion chat integrated with an interactive 3D avatar, particularly if you want to select a cloud or local language model and configure optional voice or character features.
Who it is for
- People who want a conversational AI companion presented through a 3D avatar.
- Users who want to connect a cloud model or an installed model served by Ollama or LM Studio.
- Developers interested in self-hosting or adapting an AGPL-3.0 TypeScript application.
Documented uses
- Chat with a virtual companion and see responses represented by an animated avatar.
- Select a bundled VRM character or preview a custom VRM model.
- Add optional speech input or text-to-speech through separately configured providers.
- Export companion data or import a save using replace or merge.
Requirements & limits
The repository links to a browser version that requires no installation and desktop beta builds for macOS, Windows and Linux. It identifies the project as open-source under AGPL-3.0. Desktop beta builds are unsigned and may prompt an operating-system warning on first launch.
- Utsuwa is the companion application; users configure a separate cloud or locally served LLM for chat.
- Voice input and text-to-speech are optional and have separate provider settings.
- Custom avatars use VRM files, and uploaded animation motions use VRMA files.
- The repository describes the project as early-stage and warns that save compatibility may change.
- Self-hosting the web app requires Node.js 22 or later and pnpm or npm; running the desktop app from source additionally requires Rust.
Check current requirements in the official documentation. Source-based guidance does not mean OpenViST has run or independently tested this project.
Configure a chat model and load an avatar
Set up Utsuwa for companion chat with a cloud or local model and choose its VRM character.
Before you start
- Access to Utsuwa in a browser or desktop app
- For a cloud model, an API key for the selected provider; for a local model, an Ollama or LM Studio server with an installed model
Steps
Open Settings and go to Settings > LLM Model.
Enable Chat (LLM), then choose a cloud provider and enter its API key, or select a local server and an installed model.
Go to Settings > Character and choose a bundled avatar or use Add Custom to upload a .vrm file.
Expected outcome
The app is configured to use the selected chat model and display the chosen VRM avatar.
Guide limitations
- Cloud-provider use requires its API key; local-model selection requires an installed model on the selected server.
- The repository describes Utsuwa as early-stage and advises saving data often because save states may not remain backward-compatible.
Back up or restore companion data
Export a local save or restore one using Utsuwa’s data controls.
Before you start
- Access to Utsuwa
- For restoration, a previously exported JSON save file
Steps
Open Settings > Data.
To back up, choose Export Save to download a JSON file.
To restore, choose Import Save and select the save file.
Choose Replace to wipe and restore, or Merge to add the imported data to existing data.
Expected outcome
A JSON backup is downloaded, or the selected save is restored using the chosen import mode.
Guide limitations
- The repository warns that early versions may require manual save-state reformatting and recommends saving data often.
Sources & review
Source record details
- Source availability
- Active
- Sources checked
- 12 October 2026
- Original website title
- JuiceBoxxGames/utsuwa · Official homepage title · retained in its source language
Related options
Grok Companion — The repository describes Utsuwa as an open-source alternative.