Docker Container Setup for CheetahClaws

[edwardcodelab]

Hi CheetahClaws Team,

I really appreciate the project. It's easy to set up, being a pure Python app. The plugin system is another highlight — it's really intuitive and I was able to create my own plugins with python.

That said, I've been trying to set up the CheetahClaws Docker container and finding it quite difficult.

There is no Dockerfiles in the current build.

Thanks again for this great tool — really enjoy using it!

[chauncygu]

Thanks for the kind words and the suggestion!

Quick question before I put a Dockerfile together, what's your target use case? A few options behave quite differently in Docker:

1. Web UI / chat server: long-running container, port-mapped, makes the most sense in Docker.
2. Telegram / WeChat / Slack bridge: daemon-style, also a natural fit.
3. CLI / REPL on your own files: works but needs -v $(pwd):/work -it and host config mounts; usually pip install is smoother for this.
4. CI / sandboxed eval: ephemeral, no host mounts.

Which one do you prefer (or a mix)? Once I know, I'll add a Dockerfile + README section targeted at that flow.

[edwardcodelab]

Thanks for the quick reply!

My main use case:

Home server setup in my ubuntu dgx-spark system with local ollama instance

1. Web UI
2. Telegram Bridge

workplace folder mounted in docker container from host to facilitate file exchange

to access cheetahclaws from my other PC/smart phone
smb to the workplace folder

A well-designed Dockerfile + docker-compose.yml example would be incredibly useful.

Thanks again — really loving the project!

[chauncygu]

Thanks for the detailed use case, really helpful.

See the new version:

• Dockerfile — python:3.13-slim, non-root user, tini PID-1, healthcheck
• docker-compose.yml — exactly your home-server scenario: web UI on :8080, host Ollama via host.docker.internal:11434, ./workspace bind-mounted (Samba-friendly),
  UID/GID inherited from the host
• .env.example — UID/GID/WEB_PORT/API keys
• Full guide: docs/guides/docker.md — covers Ollama connectivity, Samba sharing, Telegram bridge setup, troubleshooting

Also made cheetahclaws --web auto-start configured Telegram / WeChat / Slack bridges in the same process, so a single container delivers both the browser UI and your phone bridge.

 mkdir -p workspace data                                                                                                                                          
 docker compose up -d --build                                                                                                                                     
 # open http://<host-ip>:8080/chat 

Please give it a try and let me know if anything is rough on the DGX-Spark side.

[edwardcodelab]

Description

When running CheetahClaws in Docker, the Web UI HTML page loads (/chat returns 200), but every single static JavaScript and asset file returns 404 Not Found.

The Chat UI is completely unusable (no input box works, buttons do nothing, app is not defined error).

Steps to Reproduce

1. Build and run using the official Dockerfile + docker compose up -d
2. Start with --web --host 0.0.0.0
3. Open http://<server-ip>:8080/chat
4. Browser console shows dozens of 404 errors for:
   • /marked.min.js
   • /static/js/chat.js
   • /static/js/util.js
   • /static/js/auth.js
   • /static/js/sidebar.js
   • /static/js/tools.js
   • etc.

What I Tried

• Created symlinks in /app/web
• Copied files from static/js/ to root and static/
• Confirmed all files physically exist in the container (/app/web/static/js/*.js and /app/web/marked.min.js)
• Hard refresh + different browsers

What Works

• CLI mode (cheetahclaws) works perfectly
• Telegram bridge also works fine in CLI
• Only the Web UI is broken

Environment

• Docker on native Ubuntu
• Base image: python:3.12-slim-bookworm
• Installation: git clone → pip install -r requirements.txt && pip install .[all]
• docker-compose with command: ["cheetahclaws", "--web", "--host", "0.0.0.0"]

Cause ?

The custom web server in web/server.py uses path resolution (Path(__file__).resolve().parent).
After pip install .[all] in Docker, the expected static file paths in chat.html do not match the actual file locations on disk.

[chauncygu]

Thanks for the careful repro. Your Path(file).resolve().parent hypothesis was on the right track — small wrinkle: with pip install .[all] (non-editable), the running server reads from site-packages/web/, not /app/web/. So the symlinks and copies you placed under /app/web/ were never reachable to it.

Three independent issues underneath:

1. package-data was too narrow — pyproject.toml only listed static/js/*.js + two favicons, so a non-editable install left most of web/static/ out of site-packages/web/. The repo Dockerfile uses pip install -e '.[web]', which is why this never surfaced there.
2. Dotfile guard bug in web/server.py — it rejected any served file whose absolute path contained a .-prefixed segment, so installs sitting under .venv/, .local/, etc. would 404 every asset, even when the file existed on disk.
3. _WEB_DIR = Path(file).resolve().parent was fragile across install modes (editable / wheel / zipapp).

Fixed on the new version:

Fixed on main (14db898), use the new version: git@github.com:SafeRL-Lab/cheetahclaws.git

• _WEB_DIR now resolves via importlib.resources.files("web")
• Dotfile guard restricted to segments inside _WEB_DIR
• [tool.setuptools.package-data] widened to static/**/*
• New "Custom Dockerfile pitfalls" section in docs/guides/docker.md; symmetric Troubleshooting entry in docs/guides/web-ui.md

On your end: git pull && docker compose up -d --build should give you a healthy /chat.

[edwardcodelab]

it works! 😄