docs: rebuild KB in OKF v0.1 with live-verified facts
Copy of the legacy ~/.pi/agent/docs tree rebuilt as the command-center knowledge base: concept files promoted to path identity, index listings stripped of frontmatter, all wikilinks/relative links resolved, every checkable claim verified against the live fleet (Dankserver = Ryzen 7 7700X + RTX 3090; Strix Halo is Dankclaw), unverifiable claims tagged. kb-lint exits 0.
This commit is contained in:
Frank
@@ -0,0 +1,87 @@
|
||||
# ComfyUI
|
||||
|
||||
Node-based AI image generation engine running on `dankclaw`. Serves a web UI on port 8188.
|
||||
|
||||
## Access
|
||||
|
||||
Open `http://dankclaw:8188` in a browser. Accessible from any host on the 192.168.0.0/24 LAN.
|
||||
|
||||
## Architecture
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Host** | dankclaw (192.168.0.143) |
|
||||
| **Version** | v0.30.0 |
|
||||
| **Python** | 3.14.4, venv at `~/ComfyUI/venv` |
|
||||
| **PyTorch** | 2.13.0+cu130 (CPU backend) |
|
||||
| **Backend** | CPU — ROCm unavailable on Strix Halo (GFX13) |
|
||||
| **Model** | FLUX.2 [klein] 4B (7.3 GB, Apache 2.0) |
|
||||
| **Service** | User-level systemd, `~/.config/systemd/user/comfyui.service` |
|
||||
| **Models dir** | `~/models` via `extra_model_paths.yaml` |
|
||||
|
||||
## Directory Layout
|
||||
|
||||
```
|
||||
/home/dank/
|
||||
├── ComfyUI/
|
||||
│ ├── main.py # Entry point
|
||||
│ ├── venv/ # Python virtual environment
|
||||
│ ├── extra_model_paths.yaml # Links ~/models as model source
|
||||
│ └── models/ # ComfyUI-native model subdirs (empty)
|
||||
└── models/
|
||||
└── checkpoints/
|
||||
└── flux-2-klein-4b.safetensors
|
||||
```
|
||||
|
||||
## Service Management
|
||||
|
||||
```bash
|
||||
# Check status
|
||||
ssh dank@dankclaw 'systemctl --user status comfyui --no-pager'
|
||||
|
||||
# Restart
|
||||
ssh dank@dankclaw 'systemctl --user restart comfyui'
|
||||
|
||||
# Stop
|
||||
ssh dank@dankclaw 'systemctl --user stop comfyui'
|
||||
|
||||
# View logs
|
||||
ssh dank@dankclaw 'journalctl --user -u comfyui --no-pager -n 50'
|
||||
```
|
||||
|
||||
## Add a New Model
|
||||
|
||||
Place the `.safetensors` file in `~/models/checkpoints/`. ComfyUI detects it on restart.
|
||||
|
||||
```bash
|
||||
# Example: download a new model
|
||||
ssh dank@dankclaw 'mkdir -p ~/models/checkpoints'
|
||||
scp new-model.safetensors dank@dankclaw:~/models/checkpoints/
|
||||
ssh dank@dankclaw 'systemctl --user restart comfyui'
|
||||
```
|
||||
|
||||
## Performance
|
||||
|
||||
The AMD Ryzen AI MAX+ 395 has 16 CPU cores. ROCm does not support the Strix Halo (GFX13) APU in precompiled wheels. ComfyUI runs on CPU only. Expect generation times in the range of minutes per image.
|
||||
|
||||
## ComfyUI-Manager
|
||||
|
||||
Custom node manager installed at `~/ComfyUI/custom_nodes/ComfyUI-Manager`. Provides a UI to browse, install, and update custom nodes and models directly from the ComfyUI web interface.
|
||||
|
||||
### Install a Custom Node
|
||||
|
||||
1. Open the ComfyUI web UI
|
||||
2. Click **Manager** in the sidebar
|
||||
3. Search for the node and click **Install**
|
||||
4. Restart ComfyUI when prompted
|
||||
|
||||
### Update All Nodes
|
||||
|
||||
```bash
|
||||
ssh dank@dankclaw 'cd ~/ComfyUI && source venv/bin/activate && python custom_nodes/ComfyUI-Manager/cm-cli.sh update' && systemctl --user restart comfyui
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Troubleshooting](troubleshooting.md) — Common errors and fixes
|
||||
- [Dankclaw](../../system/dankclaw.md) — Host system overview
|
||||
@@ -0,0 +1,114 @@
|
||||
---
|
||||
type: reference
|
||||
title: ComfyUI Troubleshooting
|
||||
description: Common errors, diagnostics, and recovery steps for ComfyUI on dankclaw.
|
||||
tags:
|
||||
- image-generation
|
||||
- comfyui
|
||||
- troubleshooting
|
||||
- dankclaw
|
||||
- unverified
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# ComfyUI Troubleshooting
|
||||
|
||||
Procedures for diagnosing and fixing ComfyUI on dankclaw.
|
||||
|
||||
## Service Will Not Start
|
||||
|
||||
Check the journal logs first.
|
||||
|
||||
```bash
|
||||
ssh dank@dankclaw 'journalctl --user -u comfyui --no-pager -n 100'
|
||||
```
|
||||
|
||||
### "RuntimeError: No HIP GPUs are available"
|
||||
|
||||
Cause: The container's ROCm PyTorch cannot see the Strix Halo (gfx1151) GPU. This can happen when `/dev/kfd` and `/dev/dri` are not properly passthrough, or when the ROCm PyTorch build doesn't match the GPU architecture.
|
||||
|
||||
Fix: Verify GPU passthrough is configured in `compose.yaml` (should include `/dev/kfd` and `/dev/dri`). The container image is `comfyui-rocm:gfx1151` which should contain the correct ROCm kernels.
|
||||
|
||||
Check that the container image uses the AMD gfx1151 base:
|
||||
|
||||
```bash
|
||||
ssh dank@dankclaw 'podman inspect comfyui --format "{{.Config.Image}}"'
|
||||
```
|
||||
|
||||
If the GPU still doesn't work, ensure the host user is in the `render` group:
|
||||
|
||||
```bash
|
||||
ssh dank@dankclaw 'id dank'
|
||||
```
|
||||
|
||||
### "HIP error: invalid device function"
|
||||
|
||||
Cause: The ROCm PyTorch kernels don't match the GPU architecture. The ComfyUI container uses the AMD gfx1151 base image (`comfyui-rocm:gfx1151`), but if PyTorch was reinstalled without the ROCm build, this error occurs.
|
||||
|
||||
Fix: Reinstall the gfx1151 ROCm PyTorch. The container image already ships the correct version (torch 2.9.1+rocm). If the venv was rebuilt outside the container, reinstall:
|
||||
|
||||
```bash
|
||||
ssh dank@dankclaw 'cd ~/ComfyUI && source venv/bin/activate && \
|
||||
pip uninstall torch torchvision torchaudio pytorch-triton-rocm -y && \
|
||||
pip install torch torchvision torchaudio'
|
||||
```
|
||||
|
||||
### Port 8188 Already in Use
|
||||
|
||||
```bash
|
||||
ssh dank@dankclaw 'ss -tlnp | grep 8188'
|
||||
```
|
||||
|
||||
Kill the conflicting process or change the port in the service file.
|
||||
|
||||
## Model Not Loading
|
||||
|
||||
Check that the model file exists in the correct path.
|
||||
|
||||
```bash
|
||||
ssh dank@dankclaw 'ls -lh ~/models/checkpoints/*.safetensors'
|
||||
```
|
||||
|
||||
Verify `extra_model_paths.yaml` points to the correct base path.
|
||||
|
||||
```bash
|
||||
ssh dank@dankclaw 'cat ~/ComfyUI/extra_model_paths.yaml'
|
||||
```
|
||||
|
||||
Restart ComfyUI after adding or removing models.
|
||||
|
||||
```bash
|
||||
ssh dank@dankclaw 'systemctl --user restart comfyui'
|
||||
```
|
||||
|
||||
## Cannot Reach the Web UI
|
||||
|
||||
Test connectivity from dankware.
|
||||
|
||||
```bash
|
||||
curl -s -o /dev/null -w "%{http_code}" http://dankclaw:8188
|
||||
```
|
||||
|
||||
Expected response: `200`.
|
||||
|
||||
If the response is empty or times out, verify the service is running.
|
||||
|
||||
```bash
|
||||
ssh dank@dankclaw 'systemctl --user status comfyui --no-pager'
|
||||
ssh dank@dankclaw 'ss -tlnp | grep 8188'
|
||||
```
|
||||
|
||||
## Out of Memory
|
||||
|
||||
ComfyUI loads the full model into RAM. FLUX.2 klein 4B requires approximately 13 GB. The system has 119 GB total. Close other memory-intensive applications if OOM occurs.
|
||||
|
||||
Check memory usage.
|
||||
|
||||
```bash
|
||||
ssh dank@dankclaw 'free -h'
|
||||
ssh dank@dankclaw 'systemctl --user show comfyui --property=MemoryCurrent'
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [comfyui](index.md) — Main documentation
|
||||
Reference in New Issue
Block a user