Avatar Server Setup: Install and Configure with Docker

Setting up the Avatar Server involves three steps: adding your .hvia avatar files to the right directory, configuring a small set of environment variables in docker-compose.yaml, and starting the container. Once the server is running, your LiveKit Agent can connect to it and begin animating avatars in real time.

Prerequisites

Before you begin, make sure you have the following:

Docker and Docker Compose installed
An NVIDIA GPU with CUDA 12, OpenGL support, and at least 6 GB VRAM
NVIDIA Container Toolkit installed and configured
An Avaluma license key and at least one .hvia avatar file

Steps

Add Avatar Files

Place your .hvia avatar files in the assets/avatars/ directory inside the avatar-server/ folder:

assets/avatars/
└── your-avatar-id.hvia

The container mounts this directory at /app/assets/avatars, so any file you place here is immediately available to the server on next start.

Each .hvia file represents one avatar. You can add multiple files to run several avatars simultaneously — the only limit is your available VRAM (~2.5 GB per active session).

Configure the Environment

Open docker-compose.yaml and update the environment variables under the avaluma-avatar-server service:

environment:
  - API_SERVER_HOST=api.yourdomain.com  # Public IP or domain
  - API_UTILS_PWD=your-secure-password

Set API_SERVER_HOST to the public IP address or domain name that clients will use to reach the server. If you are running the server only on localhost without a reverse proxy, you can leave this as-is for local testing.

Variable	Description
`API_UTILS_PWD`	Password for the avatar server utility API
`API_SERVER_HOST`	Public IP or domain name of the server

Start the Server

From the avatar-server/ directory, run:

docker compose up -d

The server starts in detached mode and is available at http://localhost:8080. When you use a reverse proxy or expose the server on a public IP, make sure API_SERVER_HOST matches that address.To check that the container started successfully, inspect the logs:

docker compose logs -f

Full docker-compose.yaml Reference

Here is the complete docker-compose.yaml for reference:

services:
  avaluma-avatar-server:
    image: ghcr.io/avaluma-ai/avaluma-avatar-server:latest
    pull_policy: always # update on restart
    restart: unless-stopped
    environment:
      # change this to the Public IP of the server or domain name when using reverse proxy
      - API_SERVER_HOST=api.avaluma.ai
      - API_UTILS_PWD=CHANGE_THIS
    ports:
      # not necessary when using reverse proxy
      - 8080:8080
    volumes:
      - ./assets/avatars:/app/assets/avatars # folder for .hvia-files
    networks:
      - avaluma-net
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu, compute, utility, graphics]

networks:
  avaluma-net:
    name: avaluma-net
    driver: bridge

The image is configured with pull_policy: always, which means Docker pulls the latest image every time the container restarts. Your Avatar Server stays up to date automatically without any manual intervention.

Agents

Pricing & Billing

Avatars

Self-Hosting

Docs as MCP

Avatar Server Setup: Install and Configure with Docker

Prerequisites

Steps

Full docker-compose.yaml Reference

​Prerequisites

​Steps

​Full docker-compose.yaml Reference

Prerequisites

Steps

Full docker-compose.yaml Reference