Deploy AI Digital Human: Duix.Avatar v1.0.6

Install Duix.Avatar v1.0.6 for offline AI digital human cloning. Docker steps, 32GB RAM rule, D: drive trap, lite vs full, and real fix commands.

Drew Sullivan2026-09-256 min readIntermediate

Cloud avatar seats are easy to sell. Local Duix.Avatar v1.0.6 (ex-HeyGem) is different: it will try to mkdir on D: and pull roughly 70GB of images before you get a talking head. Skip either detail and the install dies cold.

NVIDIA-only. Docker backend. Electron client. Offline after the first pull. Repo: github.com/duixcom/Duix-Avatar · site duix.com. Client/server match for v1.0.6 comes from the current release notes (name-change alignment + Linux GPU tag fix) – re-check Releases before you pin scripts; tags move.

System requirements before you touch Docker

From the project README (as of v1.0.6 docs) – not a laptop iGPU fantasy:

Piece	Docs baseline	Recommended
OS	Windows 10 build 19042.1526+ or Ubuntu 22.04	Same tested paths
CPU	Modern multi-core	i5-13400F class
RAM	Full stack expects headroom	32GB necessary for ASR+TTS+video
GPU	NVIDIA mandatory	RTX 4070+; AMD/Intel unsupported
Disk (Windows)	Room for images + data	C: >100GB images, D: >30GB data

No host NVIDIA driver → containers never stay Running. Windows: driver first, then Docker Desktop + WSL2 (GPU rides the host driver). Ubuntu: nvidia-smi clean, then NVIDIA Container Toolkit.

Pro tip: Disk or VRAM tight? docker-compose-lite.yml is the smaller path (~one gen-video service). Lip-sync from uploaded audio only – on-box TTS/ASR and text→video are gone. Full stack is the ~70GB / 32GB RAM route.

Download the real sources

Compose lives under deploy/. Clone it:

git clone https://github.com/duixcom/Duix-Avatar.git
cd Duix-Avatar

Client builds on Releases: Windows Duix.Avatar-1.0.6-setup.exe, Linux Duix.Avatar-1.0.6.AppImage (tracks package.json 1.0.6). Images your compose pins – names drift – typically guiji2025/fun-asr, guiji2025/fish-speech-ziming, guiji2025/duix.avatar (older notes still say heygem tags). Prebuilt installer beats building from source for almost everyone.

Install the AI digital human backend (Windows path)

Confirm WSL2: wsl --list --verbose then wsl --update. Docker Desktop next – license yes, login optional.

C: tight? Move Docker’s disk image under Settings → Resources → Advanced before the big pull.

Default compose still thinks in D: paths. Create the mount targets (or you will fight this later in Errors):

mkdir D:heygem_datavoicedata
mkdir D:heygem_dataface2face
mkdir D:heygem_dataasrruntime-resourcesmodels

cd deploy
docker compose up -d
# lighter:
# docker compose -f docker-compose-lite.yml up -d
# RTX 50-series / CUDA 12.8 path:
# docker compose -f docker-compose-5090.yml up -d

First pull is slow on weak links – budget a long coffee, not a “two-minute compose.” Full stack healthy = three Running services (ASR, TTS/fish-speech, gen-video). Lite = gen-video alone. Details: README install section.

Client: run Duix.Avatar-1.0.6-setup.exe, finish NSIS, launch the desktop shortcut.

Ubuntu 22.04 (short path)

sudo apt update && sudo apt install -y docker.io docker-compose
# NVIDIA driver working, then:
sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

cd /path/to/Duix-Avatar/deploy
docker compose -f docker-compose-linux.yml up -d

chmod +x Duix.Avatar-1.0.6.AppImage
./Duix.Avatar-1.0.6.AppImage
# root desktop session:
# ./Duix.Avatar-1.0.6.AppImage --no-sandbox

First-time config that matters

No YAML ceremony. Healthy containers, then open the client on the same machine – remote client→GPU box is a side quest.

Avatar create: short clear frontal speech clip with audible voice (face + voice clone seed).
Full stack: type script (README lists English, Japanese, Korean, Chinese, French, German, Arabic, Spanish) or drop audio. Lite: audio drive only.
If you remapped volumes off D:, the UI data root must match the mounts or model add fails – same trap as the mkdir error below.

Scripting instead of clicks? Localhost ports after compose (as documented in Open APIs): TTS http://127.0.0.1:18180, video submit http://127.0.0.1:8383/easy/submit, progress /easy/query, ASR-related 10095 on full deploy. Path details live in the README and src/main/service/*.js.

Ever notice how “just Docker” projects still assume your disk letters and RAM class? That assumption is the install tax here – not the clone button.

Verify the install works

docker ps
nvidia-smi
curl -s -o NUL -w "%{http_code}" http://127.0.0.1:8383
# PowerShell: Invoke-WebRequest http://127.0.0.1:8383

Gen-video on 8383. TTS on 18180. Full deploy also touches 10095 for ASR. Client check: one short clone + one 5-10s render. Job stuck forever? docker logs on gen-video before you blame the UI.

What still feels odd after green containers – the UI, or the host GPU path? That split saves an hour of random reinstalls.

Common install errors and fixes

The catch is almost never “avatar quality.” It’s paths, stale compose, and drivers.

1. ENOENT: mkdir 'D:heygem_data...' – Windows client still targets D: even after you rewrite compose volumes. Machines without a D: partition fail model add. Community thread: create a D: partition, subst a letter, or wait for builds that expose a settings path aligned with mounts (issue #482).

2. TTS loop: No module named tools.api – stale command in compose. Turns out the fish-speech service needs python3 tools/api_server.py --listen 0.0.0.0:8080, not a tools.api module path. Pull latest compose from main, docker compose down, up again (#143 / related #370).

3. Found no NVIDIA driver inside gen-video – host driver missing/outdated, WSL GPU invisible, or Linux toolkit skipped. Fix host nvidia-smi first; on Linux re-run nvidia-ctk runtime configure + Docker restart. RTX 50-series (and some 30/40 on CUDA 12.8): official README points at docker-compose-5090.yml with the preview PyTorch path – default compose can fail CUDA init.

4. OOM / worker died on longer clips – raise Docker memory limits; bump shared memory for gen-video if your compose ships a small shm_size; close other CUDA apps.

5. Pull timeouts – registry mirror/proxy, or pull images one-by-one, then docker compose up -d.

Upgrade and uninstall

Newer Duix.Avatar-*-setup.exe over the old client. v1.0.6 notes stress matching latest server images.

cd deploy
docker compose pull
docker compose up -d

Same -f you used for 5090/linux/lite.

Cleanup:

cd deploy
docker compose down
# destructive wipe:
docker compose down -v
docker image prune -a
# delete data dirs (D:heygem_data or Linux ~/heygem_data)
# Windows: Apps & Features → uninstall Duix.Avatar

Side path if RAM is tiny: Live2D-style lightweight agents (e.g. awesome-digital-human-live2d) for chat UX under small memory budgets – different product class than offline MP4 clones.

FAQ

Do I need 32GB RAM for Duix.Avatar v1.0.6?

Full three-service stack: yes – the README calls 32GB necessary. Lite drops ASR/TTS containers, so you can try lower RAM, knowing you’re also dropping text-driven TTS.

Full compose vs lite vs 5090 – which file?

You’re on a 4070-class box with ~100GB free and you want typed scripts in a cloned voice? Default docker-compose.yml (Windows) or docker-compose-linux.yml. Only audio driving and a smaller pull? docker-compose-lite.yml. Blackwell 50-series card (or CUDA 12.8 pain on some 30/40)? docker-compose-5090.yml. Pick one profile – mixing services across files without reading mounts is how you get half-broken ports.

Can I run the client on another PC than the GPU server?

People try. 8383/18180 must be reachable, and every file path the API returns has to make sense on both machines. Supported happy path is still Docker + client on the same NVIDIA box. Split them and you’re in path-translation + firewall territory – a customization project, not the default install.

Next: nvidia-smi, free disk for images, clone the repo, bring up deploy/ with the compose file for your GPU class, install Duix.Avatar-1.0.6-setup.exe, clone a 10-second sample before production scripts.