ComfyUI Distrobox Isolation (Ubuntu Base)

This project provides a clean, reproducible, and isolated environment to run ComfyUI locally inside a Distrobox container built on Ubuntu 24.04.

Unlike configurations with multiple independent Docker stacks, this project manages only 1 consolidated instance of ComfyUI, following the official guidelines and leveraging the modern comfy-cli tool for installation and environment management.

---

1. Features

• Ubuntu 24.04 Base: High compatibility with ML libraries and tools.
• Isolated Home Directory: Container state, pip caches, python virtual environments, and custom node checkouts are isolated under a local .home/ directory in this workspace, leaving your host system clean.
• GPU Passthrough: Configured for NVIDIA GPU acceleration (CDI/CUDA), compatible with modern architectures including Nvidia Blackwell (RTX 5000 Series).
• Single Model Tree: Mounts a central models directory from the host to the container (e.g., /mnt/gigachad/comfyui/models or a local folder) mapped natively into ComfyUI's model loader.
• Comfy CLI: Utilizes the modern, official CLI tool to automate ComfyUI install, upgrades, and launches.
• Pre-installed ComfyUI-Manager: Installs ComfyUI-Manager custom node out-of-the-box.

---

2. Prerequisites

1. Distrobox (version 1.8.0 or newer recommended) and Podman or Docker installed on the host.
2. NVIDIA Proprietary Open Drivers (nvidia-driver-560-open or similar compatible version) and the NVIDIA Container Toolkit (nvidia-container-toolkit) installed on the host.
   • For Blackwell (RTX 5000 / RTX 5060 Ti) GPUs, ensure you are running the open kernel modules.

---

3. Quick Start

Step 1: Configure Environment Variables

Copy the template .env.example to .env:

cp .env.example .env

Edit .env to customize your:

• PORT: Port where ComfyUI will run on the host (defaults to 8188).
• MODELS_DIR: Absolute path to where your models (checkpoints, loras, vaes, etc.) are located on the host/NAS.

Step 2: Create and Provision the Container

Create the container and trigger internal script setup (this will take a few minutes as it downloads packages and installs PyTorch with CUDA support):

make setup

This automates the following steps:

1. Generates distrobox.ini mapping your custom .env paths.
2. Builds the Distrobox container comfyui-ubuntu.
3. Creates a virtual environment (~/comfy-venv) inside the container.
4. Installs comfy-cli and sets up ComfyUI optimized for Nvidia GPUs.
5. Populates extra_model_paths.yaml to read from the mounted /mnt/comfyui-models.
6. Pre-installs ComfyUI-Manager.

Step 3: Run ComfyUI

Start the server:

make start

Open your browser and navigate to http://localhost:8188 (or the custom port you configured).

---

4. Commands Reference

All orchestration is managed via the Makefile in the root:

Command	Action
make create	Creates the container without installing packages.
make setup	Provisions Python, ComfyUI, Comfy-CLI, and setup model mappings.
make start or make run	Starts the ComfyUI server.
make enter	Opens an interactive bash shell inside the container.
make status	Checks the registered distrobox containers.
make stop	Stops the running container.
make destroy	Destroys the container and deletes the generated distrobox.ini.
make clean-all	Destroys the container, deletes .home/ (cache and libs) and .env.

---

5. Directory Structure

distrobox-comfyui/
├── Makefile                 # Automation rules
├── distrobox.ini.template   # Declarative Distrobox spec
├── setup.sh                 # Internal provisioning script (comfy-cli)
├── run.sh                   # Startup wrapper script
├── .env.example             # Template for variables
├── .gitignore               # Ignored local structures
├── .home/                   # Isolated home directory (Git ignored)
└── models/                  # Fallback local models folder (Git ignored)