LocalAGI + existing LocalAI on Docker Desktop (Windows 11) – startup hangs, model path conflicts, avatar/HUD crash, endpoint mismatch”

I was working with openAI 4o (Didn't realize 3o was the now better decision maker now that 1o is gone) to get these local AI/AGI up and running. I think a warning may help that if the user already has localai running that the localagi install progress will be different, or they need to shutdown the current running localai. Maybe a config that detects a localai running and uses that instead of trying to install another localai in the localagi container.

OpenAI gpt4o helped me write this up. If something does not make sense let me know.

Title

LocalAGI vs. pre‑existing LocalAI on Docker Desktop (Windows 11): endpoint mismatch, avatar crash, frequent Docker hang

---

Description

Host setup

• OS: Windows 11 Pro
• Docker Desktop: Hyper‑V backend
• LocalAI: started first (localai/localai:latest-aio-cpu) with port mapping -p 8080:8080
• LocalAGI: added afterwards via docker compose up inside E:\AI\localai\LocalAGI

---

1. Port collision and DNS mismatch

• The localagi service maps its Web UI to host port 8080 (- 8080:3000)
• Our pre-existing LocalAI was already bound to 8080:8080 on the host
• LocalAGI's Web UI failed to load or froze
• Agents failed repeatedly with lookup localai on 127.0.0.11:53: no such host → 5 retries → 500 error
• LocalAI running separately was never visible to LocalAGI via Docker DNS

2. Avatar / HUD crash

• Creating a new agent with HUD enabled caused a hard crash
• Missing Stable Diffusion backend leads to EOF or model-not-found errors
• Web UI froze; container Exec and Files tabs in Docker Desktop became unresponsive

3. Missing .env guidance

• The docs mention LOCALAI_API, but no .env is shipped
• Setting API_URL had no effect
• It's unclear which variable (e.g. LOCALAI_API, API_URL) is honored where

4. Repeatable freeze during compose shutdown / restart

• Running docker compose down frequently caused Docker Desktop to freeze
• Possibly a Docker Desktop issue, but the symptoms appear tied to LocalAGI when multiple services are downing together

---

Steps to reproduce

1. docker run -d -p 8080:8080 --name localai localai/localai:latest-aio-cpu
2. Verify that LocalAI responds on localhost:8080
3. Clone LocalAGI: git clone https://github.com/mudler/LocalAGI
4. Run docker compose up -d
5. Attempt to create agent with HUD enabled
6. Observe freeze and no such host errors
7. Update .env or config to use host.docker.internal:8080
8. Observe partial fix but ongoing issues unless ports are remapped

---

Suggested improvements

• Container DNS override: support LOCALAI_EXTERNAL_URL or equivalent to bypass internal hostname
• Ship .env.example with clear variable expectations and format
• Disable avatar/HUD by default or show user-facing warnings if unsupported
• Log helpful errors instead of hard failures when agents can’t resolve localai
• Add depends_on: or network isolation info to reduce startup confusion with pre-existing LocalAI setups

Thanks again — happy to test further if you need repros!

Start with the Docker Compose configuration and the documented environment variables, especially the LocalAI endpoint settings and port mappings. Reproduce the separate LocalAI setup on Docker Desktop, then trace the DNS, HUD, and shutdown failures. Done means the existing LocalAI can be used without port or hostname errors, HUD failures are handled, and the configuration guidance is clear.