🤖 Avatar Companion

Give your AI a face. A WebXR avatar you can chat with — works offline out of the box, and optionally connects to your own LLM and text-to-speech.

Install & availability

Available now. Install from the Companion Hub App Store. Verified on the test fleet: the published image pulls, starts, serves its web UI, and survives a container restart.


Hub App Store	Search Avatar Companion → Install
Container image	`ghcr.io/companionintelligence/ci-spatial-companion-webxr:latest` (public)
Web UI port	`5173`
Architecture	`linux/amd64` and `linux/arm64` (multi-arch)

Overview

Avatar Companion gives your Companion AI a visual, spatial presence: a 3D avatar you can chat with in a browser, with optional WebXR for headsets. It works offline out of the box — the avatar renders, animates, and responds using a built-in script provider (scripted responses) with no backend required. Connecting it to a real LLM and to speech synthesis is optional and described below.

Current capabilities

What Avatar Companion does today, as shipped:

Avatar rendering, chat, and animations with no backend, via the default scripted-response provider
Works offline out of the box — install and chat immediately
WebXR for viewing on a headset (optional; not required for desktop use)
Optional LLM (Ollama / Hub inference, or in-browser WebLLM) and optional TTS — see configuration below

By default, speech is silent unless a TTS server is reachable; the avatar still chats via text and animation.

Connecting a real LLM or TTS requires a rebuild, not a runtime flag. This is a Vite app, so environment variables are baked into the bundle at build time. Passing -e VITE_LLM_* to the running container has no effect. To connect Ollama or Hub inference you must rebuild the image with --build-arg VITE_LLM_* set.

Connecting an LLM

There are two providers:

Remote LLM (Ollama / Hub inference): set VITE_LLM_PROVIDER plus the VITE_LLM_* URL/model build args and rebuild the image.
In-browser (WebLLM): set VITE_LLM_PROVIDER=mlc to run a model entirely in the browser via WebLLM . This needs WebGPU support in the client browser.

LLM and TTS requests originate in the user’s browser, not the container. That means the Ollama (or TTS) URL you bake in must be reachable from the client device, and Ollama must allow cross-origin requests from the app’s origin (set OLLAMA_ORIGINS accordingly). A URL that only resolves inside the Hub network will fail from a phone or laptop on the LAN.


# Example: build with a remote Ollama the client can reach, plus CORS allowed on Ollama
docker build \
  --build-arg VITE_LLM_PROVIDER=ollama \
  --build-arg VITE_LLM_URL=http://hub.lan:11434 \
  --build-arg VITE_LLM_MODEL=llama3.2:3b \
  -t ci-spatial-companion-webxr:custom .

Use Cases

Chat with an embodied avatar in the browser — no setup, works offline
Connect your own local LLM for real conversational responses
View the avatar in a WebXR headset
Run a fully in-browser model via WebLLM on a WebGPU-capable device

Supported Platforms

Platform	Mode	Notes
Desktop browser (Chrome, Edge)	WebXR / 2D	Works offline; mic needs a secure context
WebXR headset	Immersive	Where the browser supports WebXR
iOS / Android	2D / AR	Mic and camera need HTTPS

Setup

Install from Hub

Search for Avatar Companion in the Hub app store and install. It works immediately with scripted responses — no further configuration needed.

Open the client

Navigate to http://avatar.ci.localhost. Click Enter to launch. No headset required for desktop use.

(Optional) Connect an LLM and TTS

Rebuild the image with the VITE_LLM_* build args (and a reachable TTS server) as shown above, then install your custom build. Remember the URLs must be reachable from the client device with CORS allowed.

Usage

Chatting

Type to the avatar; it animates and responds. With the default provider, responses are scripted. With an LLM configured, responses come from your model.

Voice

Microphone input requires a secure context (HTTPS). Spoken replies are silent unless a TTS server is reachable from the client.

Entering XR

In a WebXR-capable browser or headset, click Enter XR to switch to immersive mode.

Troubleshooting

LLM connection ignored at runtime VITE_LLM_* envs are baked at build time — -e at runtime does nothing. Rebuild the image with --build-arg.

LLM/TTS unreachable Requests come from the browser, not the container. Ensure the URL resolves from the client device and that Ollama allows the app’s origin via OLLAMA_ORIGINS.

Microphone not working Mic access requires HTTPS. Open the app over a secure hostname.

WebLLM won’t load The mlc provider needs WebGPU in the client browser. Verify WebGPU support is enabled.