ROCmRoll

ROCmRoll is a Windows-native platform manager for portable ComfyUI environments optimized for AMD Radeon GPUs using ROCm and PyTorch. It helps users create, launch, update, diagnose, and repair reproducible ComfyUI instances while reducing the setup friction commonly associated with AMD GPU workflows on Windows.

ROCmRoll keeps its orchestration outside ComfyUI:

ROCmRoll owns runtimes, environments, caches, manifests, state, logs, launchers, diagnostics, repair flows, and package installation.
Each ComfyUI instance owns its checkout, instance-local custom_nodes, generated configuration, and instance metadata.
Heavy assets such as models, input, output, temp files, and optional workflows are shared outside the ComfyUI source tree.

See docs/architecture.md for the implementation architecture.

Table of contents

Status
Requirements
Quick Start
Instance Overlays
Declarative Instances
Channels
Profiles
Supported GPU Families
What Install Does
Project Layout
Configuration
Workspaces
Command Reference
Examples
Runtime And ROCm
Custom Nodes, Packages, And Patches
Launch Behavior
State, Logs, Locks, And Cache
ComfyUI Desktop Integration
Troubleshooting
Development Notes
Credits
License

Status

This repository contains the active PowerShell implementation.

Implemented areas include:

Thin rocmroll.bat wrapper around source\rocmroll.ps1
Full install orchestration through PowerShell modules
Python 3.12.10 runtime creation from embeddable Python plus full ZIP enrichment
Per-instance Python environments
AMD GPU detection with manual --gfx override
Stable, preview, nightly, legacy, and legacy-staging channel manifests
ComfyUI Git mirror cache and per-instance clone
Instance-local custom node install/update
Generated extra_model_paths.yaml, preserved on update/repair and overridable via a custom overlay
Declarative import/plan/apply/destroy top-level commands on top of an optional YAML instance definition, reusing the imperative install/update/remove pipeline under the hood
Generated launchers under launchers\
Shared asset folders
ROCm/PyTorch validation via source\scripts\validate-rocm.py
Registry-driven instance, doctor, env, rocm, comfyui, cache, state, logs, config, profile, patch, and workspace command families
JSON state files, human logs, JSONL logs, and PID lock files
Optional ComfyUI Desktop registration
User configuration through rocmroll.ini
Named workspaces for path sets
Execution profiles for environment variables and ComfyUI launch arguments

Requirements

ROCmRoll targets:

Windows only
PowerShell 5.1 or newer
Git available in PATH
An AMD Radeon, Radeon Pro, or Instinct GPU mapped in source\manifests\rocm-architectures.json, or a manual --gfx override
AMD graphics driver installed
Long path support enabled in Windows, strongly recommended
An ASCII-only install path, recommended
Network access to Python, PyPI, GitHub, AMD ROCm package endpoints, and ROCm nightly indexes
Enough disk space for Python runtimes, ComfyUI checkouts, ROCm/PyTorch wheels, caches, models, and outputs

Unsupported by design:

Linux, WSL, and macOS
NVIDIA and Intel GPU backends
Global custom node sharing across all instances
Silent modification of ComfyUI source files outside managed patches

Quick Start

Run commands from the repository root.

Initialize the folder layout:

.\rocmroll.bat init

Check the host system:

.\rocmroll.bat doctor --system
.\rocmroll.bat doctor --gpu

Create a stable ComfyUI instance:

.\rocmroll.bat instance install --name rocm-stable --channel stable

Launch it:

.\rocmroll.bat instance launch --name rocm-stable

The generated launcher starts ComfyUI on:

http://127.0.0.1:8188

Use a different port at launch time:

.\rocmroll.bat instance launch --name rocm-stable --port 8189

If more than one ready instance exists, instance launch can run without --name and ROCmRoll will show an interactive selector:

.\rocmroll.bat launch

Instance Overlays

ROCmRoll supports per-instance resource overlays in the overlays\ folder at the repository root. Files placed there are loaded after the global manifests/templates and do not require editing any source file. This is also where declarative instance YAML definitions live - see Declarative Instances below.

Layout

overlays\
  <instanceName>\
    <instanceName>.yaml           Optional declarative instance definition
    environment\
      requirements.txt            Optional extra pip packages for this instance
    instance\
      custom_nodes.json           Optional extra custom nodes for this instance
      extra_model_paths.yaml      Optional overlay for this instance's extra_model_paths.yaml

The overlay folder always takes priority over ROCmRoll's built-in defaults: extra_model_paths.yaml uses the overlay instead of the template whenever an overlay file exists; requirements.txt and custom_nodes.json overlays are installed in addition to ComfyUI's/the default manifest's own, after them.

Custom requirements

Place a standard requirements.txt in overlays\<instanceName>\environment\:

overlays\rocm-stable\environment\requirements.txt

ROCmRoll installs it after ComfyUI's own requirements.txt using the same pip cache and upgrade strategy. A non-zero pip exit code is a fatal error and reports ROCMROLL-COMFY-005.

This file is picked up by every code path that runs ComfyUI dependency installation:

instance install
comfyui requirements
instance update --comfyui
instance repair --comfyui

Custom nodes

Place a custom_nodes.json in overlays\<instanceName>\instance\ using the same format as source\manifests\custom-nodes.json:

{
  "default": [
    {
      "name": "MyCustomNode",
      "repo": "https://github.com/user/MyCustomNode.git",
      "ref": "main",
      "installRequirements": true
    }
  ]
}

ROCmRoll clones and configures these nodes after the default manifest nodes. Clone failures are non-fatal warnings. The list is processed by every code path that handles custom nodes:

instance install
comfyui nodes --install / --update
instance repair --custom-nodes

Custom extra_model_paths.yaml

Place a custom extra_model_paths.yaml in overlays\<instanceName>\instance\:

overlays\rocm-stable\instance\extra_model_paths.yaml

If present, ROCmRoll renders this file (with {SharedFolder} substituted) into instances\<instanceName>\extra_model_paths.yaml whenever the file needs to be generated. Without an overlay, ROCmRoll falls back to source\templates\extra_model_paths.yaml.tpl.

instance update and comfyui update never overwrite an existing extra_model_paths.yaml, even if the overlay or template changed - your edits are always preserved. instance repair --comfyui regenerates it automatically only if it still matches what ROCmRoll last wrote; if it looks hand-edited, repair asks for confirmation (or pass --force to skip the prompt). See docs/declarative-instances.md for full details.

The overlays\ folder is root-relative and is not user-configurable in rocmroll.ini.

Declarative Instances

ROCmRoll can be driven two ways: imperatively, with the instance commands above (simple, one command at a time), or declaratively, by describing an instance as YAML and letting ROCmRoll converge to it - import, plan, apply, and destroy are top-level commands (not instance subcommands), following the same plan/apply split as Terraform's main commands. apply is capable of everything instance install/instance update can do, since for anything beyond a small config-file reconciliation it calls the exact same underlying pipeline under the hood; destroy is the equivalent counterpart for instance remove --all.

.\rocmroll.bat import --name rocm-stable
.\rocmroll.bat plan --file .\overlays\rocm-stable\rocm-stable.yaml
.\rocmroll.bat apply --file .\overlays\rocm-stable\rocm-stable.yaml
.\rocmroll.bat destroy --name rocm-stable

import reverse-engineers overlays\<name>\<name>.yaml from an already-installed instance's recorded state and filesystem, so you don't have to hand-write the schema for instances you already have. plan compares the YAML definition, ROCmRoll's recorded state, and the actual filesystem, then prints a classified list of changes (create/update/preserve/warning/destructive) before anything happens. apply executes that plan - a genuinely new or under-provisioned instance gets the full install/update pipeline (Python runtime, environment, ROCm/PyTorch, ComfyUI, custom nodes, packages, patches, launchers); a plan with only small changes (e.g. just the launcher is missing) only does that - and it blocks anything destructive unless you pass --allow-destructive. apply --file X computes and applies a plan directly in one step; apply --plan X.plan.json --file X applies a plan plan --output saved earlier. destroy tears down the checkout, environment, launchers, and recorded state - shared assets and the instance's overlays\<name>\ files are always preserved - and requires typing the instance's name to confirm unless --auto-approve is passed.

This is entirely optional - existing instance install/update/repair/remove workflows are unaffected, and the declarative commands reuse them rather than duplicating them. See docs/declarative-instances.md for the YAML schema, the full plan/apply/destroy reference, and destructive-action safeguards.

Channels

Channels are defined in source\manifests\channels.json.

Channel	ComfyUI ref	ROCm source	Default profile	Notes
`stable`	`v0.33.0`	AMD ROCm 7.2.1 direct URLs	`stable`	Pinned ROCmRoll baseline; Python 3.12 required
`preview`	`master`	`https://rocm.nightlies.amd.com/whl-multi-arch/`	`optimized`	AMD's unified multi-arch wheel index (promoted)
`nightly`	`master`	`https://rocm.nightlies.amd.com/whl-staging-multi-arch/`	`optimized`	Staging multi-arch index; more volatile than preview
`legacy`	`master`	`https://rocm.nightlies.amd.com/v2/<rocmIndex>/`	`optimized`	Per-GPU-family v2 index (pre-multi-arch scheme)
`legacy-staging`	`master`	`https://rocm.nightlies.amd.com/v2-staging/<rocmIndex>/`	`optimized`	Per-GPU-family v2-staging index; serves gfx942/gfx950

Stable currently installs:

Python 3.12.10
ROCm 7.2.1
torch 2.9.1+rocm7.2.1
torchvision 0.24.1+rocm7.2.1
torchaudio 2.9.1+rocm7.2.1

preview and nightly install from AMD's unified multi-arch wheel indexes. Those are single flat package indexes covering every supported GPU rather than one folder per family, so package selection happens through pip extras keyed to the exact GPU chip instead of the index URL: torch[device-gfx1100], torchvision[device-gfx1100], torchaudio, rocm[libraries,devel,device-gfx1100]. ROCmRoll resolves the exact chip (not just the GPU family) automatically during detection - see "Supported GPU Families" below. preview uses the promoted index, nightly the staging index, mirroring the old v2/v2-staging split.

legacy and legacy-staging keep the older per-GPU-family index scheme (v2/v2-staging plus a rocmIndex folder such as gfx110X-all), installing generic torch, torchvision, torchaudio, and rocm[libraries,devel]. They exist as a fallback for GPUs not yet published on the multi-arch indexes and for anyone who needs the previous behavior.

Automatic Channel Switching

Channel switching is manifest-driven through two optional per-family flags in source\manifests\rocm-architectures.json (absent means supported):

Flag	Families	Effect
`stableSupported: false`	`gfx101X` (RDNA 1), `gfx103X` (RDNA 2)	`--channel stable` automatically switches to `preview`; AMD publishes no official Windows stable release wheels for these families
`multiArchSupported: false`	`gfx94X` (MI300/MI325), `gfx950` (MI350/MI355)	`--channel preview`/`nightly` automatically switches to `legacy-staging`; AMD does not publish multi-arch Windows wheels for these families yet

RDNA 1 and RDNA 2 are experimental on Windows ROCm and now install from the multi-arch preview/nightly channels like every other supported family. The former dedicated rdna1/rdna2 channels were removed; instances installed with them are transparently treated as preview (see "Channel Migration" below).

Channel Migration

Instance state records the channel it was installed with. Removed channel names are aliased to their replacements at every lookup, so existing instances keep working without manual edits:

Old channel	Now resolves to
`rdna1`	`preview`
`rdna2`	`preview`

The canonical name is written back to instance state on the next full instance install/instance update.

Profiles

Execution profiles are JSON presets that control process-local environment variables and ComfyUI launch arguments. The active profile is loaded by the generated launcher at runtime, so you can switch behavior without reinstalling.

Profiles live in profiles\ by default. The folder is configurable through rocmroll.ini.

Profile file	Profile	Default channel	Summary
`stable.json`	`stable`	`stable`	Baseline AMD profile with minimal env vars
`stable-dynamic-vram.json`	`stable-dynamic-vram`	none	Baseline plus `--enable-dynamic-vram`
`optimized.json`	`optimized`	`preview`, `nightly`, `legacy`, `legacy-staging`	Flash-Attention Triton, MIOpen settings, SageAttention, dynamic VRAM
`flash-attention.json`	`flash-attention`	none	Flash-Attention Triton backend, MIOpen settings, dynamic VRAM; Triton autotuning disabled
`flash-attention-autotune.json`	`flash-attention-autotune`	none	Like `flash-attention` but with `FLASH_ATTENTION_TRITON_AMD_AUTOTUNE=TRUE`
`sage-attention.json`	`sage-attention`	none	SageAttention backend, MIOpen settings, dynamic VRAM; Triton autotuning disabled
`sage-attention-autotune.json`	`sage-attention-autotune`	none	Like `sage-attention` but with `FLASH_ATTENTION_TRITON_AMD_AUTOTUNE=TRUE`
`performance-autotune.json`	`performance-autotune`	none	Aggressive MIOpen and Triton autotuning
`experimental.json`	local experimental content	none	Check file contents before using; it currently contains an object named `optimized`

Profile commands:

.\rocmroll.bat profile list
.\rocmroll.bat profile show --name optimized
.\rocmroll.bat profile create --name my-profile
.\rocmroll.bat profile remove --name my-profile

Use a profile at install time:

.\rocmroll.bat instance install --name rocm-stable --profile stable-dynamic-vram

Override a profile at launch time:

.\rocmroll.bat instance launch --name rocm-stable --profile performance-autotune

Apply a profile to an existing instance (regenerates launchers and updates ComfyUI Desktop):

.\rocmroll.bat profile apply --instance rocm-stable --profile flash-attention

Omit --profile to apply the channel default:

.\rocmroll.bat profile apply --instance rocm-stable

Profile JSON shape:

{
  "name": "my-profile",
  "description": "Description shown in profile list",
  "version": "1.0",
  "defaultForChannels": [],
  "env": {
    "COMFYUI_ENABLE_MIOPEN": "0"
  },
  "launchArgs": [
    "--disable-smart-memory",
    "--use-sage-attention"
  ],
  "legacyGpuOverrides": {
    "env": {
      "TORCH_BACKENDS_CUDA_MATH_SDP_ENABLED": "1"
    },
    "launchArgs": [
      "--use-quad-cross-attention"
    ]
  }
}

Supported GPU Families

GPU mapping lives in source\manifests\rocm-architectures.json.

GFX family	ROCm index	Architecture	Status
`gfx120X`	`gfx120X-all`	RDNA 4	Supported
`gfx1150`	`gfx1150`	RDNA 3.5 / Strix Point	Supported
`gfx1151`	`gfx1151`	RDNA 3.5 / Strix Halo	Supported
`gfx1152`	`gfx1152`	RDNA 3.5 / Krackan Point	Supported
`gfx1153`	`gfx1153`	RDNA 3.5	Supported
`gfx110X`	`gfx110X-all`	RDNA 3	Supported
`gfx103X`	`gfx103X-all`	RDNA 2	Experimental
`gfx101X`	`gfx101X-dgpu`	RDNA 1	Experimental
`gfx90X`	`gfx90X-dcgpu`	Radeon Pro VII	Supported
`gfx94X`	`gfx94X-dcgpu`	MI300 / MI325	Supported
`gfx950`	`gfx950-dcgpu`	MI350 / MI355	Supported

Manual override example:

.\rocmroll.bat instance install --name rocm-stable --gfx gfx120X

Exact GPU Chip Resolution (Multi-Arch Channels)

Each family above bundles one or more physical GPU chips (for example gfx110X covers gfx1100, gfx1101, gfx1102, and gfx1103). The stable/legacy/legacy-staging channels only need the family-level rocmIndex because AMD publishes one wheel index per family. The multi-arch indexes used by preview and nightly need the exact chip instead, since ROCm SDK device packages are published per chip, not per family.

Each family entry in rocm-architectures.json has a chips array mapping device names to exact chip ids. GPU detection resolves both the family (gfx/rocmIndex, used by the per-family channels) and the exact chip (multiArchChip, used by preview and nightly) from the same detected device name. When --gfx overrides to a family key instead of detecting hardware, ROCmRoll defaults multiArchChip to the first chip listed for that family.

What Install Does

The full install command:

.\rocmroll.bat instance install --name rocm-stable --channel stable

performs this high-level flow:

Initializes folder structure and cache folders.
Creates or reuses the Python runtime.
Creates or reuses the per-instance Python environment.
Detects the AMD GPU and resolves the ROCm index.
Installs ROCm/PyTorch packages for the selected channel.
Clones or updates the ComfyUI instance from the Git mirror cache.
Installs ComfyUI requirements.txt.
Generates extra_model_paths.yaml.
Optionally links workflows to shared\workflows.
Installs default custom nodes.
Installs the rocm-performance package profile.
Applies applicable ComfyUI source patches.
Generates launchers.
Binds the instance path into the environment _pth file.
Writes instance and environment state.
Registers the instance in ComfyUI Desktop if Desktop is present.
Runs validation.

Re-running the same install is intended to converge the instance to the requested state and reuse caches.

Project Layout

Source and documentation:

rocmroll.bat                    Thin Windows wrapper
source\rocmroll.ps1            Main CLI entrypoint
source\modules\                PowerShell modules
source\scripts\                Helper scripts
source\manifests\              Channel, runtime, GPU, package, and node manifests
source\patches\                Package and ComfyUI patch definitions
source\templates\              Generated launcher and config templates
profiles\                      Execution profile JSON files
workspaces\                    Workspace JSON files
overlays\                      Per-instance overlays: requirements.txt, custom_nodes.json,
                                extra_model_paths.yaml, and declarative <name>.yaml definitions
docs\architecture.md           Current architecture reference
docs\declarative-instances.md  Declarative instance schema and plan/apply/destroy reference

Generated runtime layout:

rocmroll.ini                   Optional user configuration
.cache\                        Download, pip, Git, wheelhouse, checksum, and tool caches
.state\                        Runtime, environment, instance, patch, lock, and global state
.temp\                         Temporary extraction/work folder
environments\                  Per-instance Python environments
instances\                     Per-instance ComfyUI checkouts
launchers\                     Generated .ps1 and .bat launchers
logs\                          Install, launch, update, doctor, and crash logs
runtimes\                      Shared Python runtimes
shared\input\                  Shared ComfyUI input
shared\output\                 Shared ComfyUI output
shared\temp\                   Shared ComfyUI temp
shared\user\                   Shared user-data root
shared\models\                 Shared model storage
shared\workflows\              Optional shared workflows target

Configuration

ROCmRoll reads optional configuration from rocmroll.ini.

Create the file with defaults commented out:

.\rocmroll.bat config init

Show resolved paths:

.\rocmroll.bat config show

Supported [paths] keys:

Key	Default	Purpose
`shared`	`shared`	Shared input, output, temp, user, models, workflows
`userdata`	`shared\user`	ComfyUI user-data root
`instances`	`instances`	ComfyUI checkouts
`environments`	`environments`	Python environments
`runtimes`	`runtimes`	Python runtimes
`launchers`	`launchers`	Generated launchers
`profiles`	`profiles`	Execution profiles
`logs`	`logs`	Logs
`state`	`.state`	State, locks, patch backups
`cache`	`.cache`	Download and package caches

Example:

[paths]
shared       = D:\comfy\shared
instances    = D:\comfy\instances
environments = D:\comfy\environments
cache        = D:\.cache\rocmroll

Relative paths are resolved from the ROCmRoll root folder. Source files and workspaces\ remain root-relative and are not redirectable.

Workspaces

A workspace is a named set of path overrides stored in workspaces\<name>.json.

Path precedence:

--workspace NAME on the command line
Active workspace from [active] in rocmroll.ini
[paths] in rocmroll.ini
Built-in defaults

instance list --all is the exception used for inventory: it resolves the base [paths] configuration without the active workspace, then resolves every named workspace once. --all and --workspace cannot be combined.

Use a workspace for one command without changing the active workspace:

.\rocmroll.bat instance install --name rocm-stable --workspace staging
.\rocmroll.bat doctor --instance rocm-stable --workspace production
.\rocmroll.bat instance launch --name rocm-stable --workspace staging

Workspace commands:

.\rocmroll.bat workspace list
.\rocmroll.bat workspace show --name staging
.\rocmroll.bat workspace create --name staging
.\rocmroll.bat workspace use --name staging
.\rocmroll.bat workspace edit --name staging
.\rocmroll.bat workspace remove --name staging
.\rocmroll.bat workspace init --name staging

Command Reference

Get help:

.\rocmroll.bat help
.\rocmroll.bat help instance install
.\rocmroll.bat instance install --help
.\rocmroll.bat help options

Common commands:

Command	Purpose
`instance install`	Full install: runtime, environment, ROCm/PyTorch, ComfyUI, custom nodes, packages, launchers
`instance launch`	Launch a ready instance
`instance update`	Refresh all components, or selected environment, ROCm, and ComfyUI components
`doctor`	Run diagnostics and health checks
`instance repair`	Repair all components or an explicit component scope, including managed patches
`instance list`	List installed instances in one workspace or all workspaces
`instance remove`	Remove a complete instance or an explicit component scope
`cache`	Inspect, verify, clean, or prune caches

Advanced commands:

Command	Purpose
`init`	Initialize folder structure
`rocm info`	Show ROCm/PyTorch and GPU info for an instance
`rocm validate`	Run ROCm/PyTorch validation for an instance
`comfyui info`	Show ComfyUI and custom node info
`comfyui requirements`	Reinstall ComfyUI requirements
`comfyui nodes`	List, install, update, or add custom nodes
`comfyui update`	Update the ComfyUI source checkout and optionally reapply patches
`config`	Show or create `rocmroll.ini`
`profile`	Manage execution profiles
`patch`	List, apply, or remove ComfyUI source patches
`workspace`	Manage named path workspaces
`logs`	Show recent log files
`import`	Generate a declarative YAML definition from an existing instance
`plan`	Show planned changes for a declarative instance YAML definition
`apply`	Apply a declarative instance YAML definition (same install/update pipeline as `instance install`/`update`)
`destroy`	Destroy an instance's checkout, environment, launchers, and state (shared assets and overlays preserved)
`help`	Show command help

Global options accepted by every command:

Option	Meaning
`--quiet`	Suppress non-error output
`--verbose` / `--debug`	Show more native command output
`--json`	Emit structured JSON where supported
`--no-color`	Disable colored console output
`--log-level LEVEL`	Set the logging threshold
`--log-file PATH`	Write a log file
`--help`	Show help

Common command-specific options:

Option	Used by
`--workspace NAME`	Commands whose help explicitly lists workspace selection
`--channel stable\|preview\|nightly\|legacy\|legacy-staging`	Instance install and list filtering
`--python VERSION`	Instance install; default `3.12.10`
`--name NAME`	Instance aggregate commands, `plan`/`apply`/`destroy`/`import`, and workspace, environment, or profile commands
`--instance NAME`	Doctor, ROCm, ComfyUI, `profile apply`, and patch commands
`--environment`, `--rocm`, `--comfyui`, `--patches`, `--all`	Component scopes listed by instance info/update/repair/remove help
`--profile NAME`	Instance install, launch, and `profile apply`
`--force`	Forced install/update/removal, stale install-lock override, or skip repair's managed-file confirmation
`--gfx ARCH`, `--port PORT`, `--url HOST`, `--patch-id ID`, `--shared-workflows`	Specialized commands shown in command help
`--file PATH`	`plan`/`apply`/`destroy`: path to a ComfyUIInstance YAML definition
`--output PATH`	`plan`: write the plan as JSON to this path; `import`: write the definition to this path
`--plan PATH`	`apply`: apply a previously saved plan JSON instead of regenerating one
`--auto-approve`, `--dry-run`	`apply`/`destroy`: skip confirmation, or preview only
`--allow-destructive`	`apply`: allow destructive actions

Examples

# Create instances
.\rocmroll.bat instance install --name rocm-stable
.\rocmroll.bat instance install --name rocm-preview --channel preview
.\rocmroll.bat instance install --name rocm-nightly --channel nightly

# Launch
.\rocmroll.bat instance launch --name rocm-stable
.\rocmroll.bat instance launch --name rocm-stable --port 8189
.\rocmroll.bat instance launch --name rocm-stable --profile performance-autotune

# Update and repair
.\rocmroll.bat instance update --name rocm-stable
.\rocmroll.bat instance update --name rocm-stable --comfyui
.\rocmroll.bat instance update --name rocm-stable --force
.\rocmroll.bat instance repair --name rocm-stable --patches

# Diagnostics
.\rocmroll.bat doctor --system
.\rocmroll.bat doctor --gpu
.\rocmroll.bat doctor --instance rocm-stable
.\rocmroll.bat doctor --instance rocm-stable --json

# Custom nodes
.\rocmroll.bat comfyui nodes --instance rocm-stable
.\rocmroll.bat comfyui nodes --instance rocm-stable --update
.\rocmroll.bat comfyui nodes --instance rocm-stable --add https://github.com/user/ComfyUI-Node.git

# Remove
.\rocmroll.bat instance remove --name rocm-stable --patches
.\rocmroll.bat instance remove --name rocm-stable --environment
.\rocmroll.bat instance remove --name rocm-stable --all
.\rocmroll.bat instance remove --name rocm-stable --all --force

With no component flags, instance info, instance update, and instance repair default to all supported scopes. instance remove always requires an explicit scope. Partial removal preserves the instance state as incomplete so it can be repaired; successful repair clears the restored component markers and returns the instance to ready when none remain. Removing patches restores their backed-up source files before deleting patch metadata. instance remove --all removes the checkout, environment, launchers, instance/environment state, patch artifacts, and ComfyUI Desktop registration while preserving shared assets.

Runtime And ROCm

The default runtime is Python 3.12.10, controlled by RuntimeVersion and source\manifests\python-runtimes.json.

ROCmRoll downloads embeddable Python, enriches it with include, libs, and Lib from the full Python ZIP, bootstraps pip, upgrades pip, setuptools, and wheel, and writes runtime state.

Per-instance environments are copied from the runtime and named like:

<instance>-py312

ROCm/PyTorch installation is selected by channel. index-source installs (legacy, legacy-staging) can use wheels from .cache\wheelhouse\<rocmIndex>\ through --find-links when that folder contains wheels; the multiArch-source channels (preview, nightly) use .cache\wheelhouse\<multiArchChip>\ instead, keyed by the exact GPU chip.

Manual ROCm validation:

.\rocmroll.bat rocm validate --instance rocm-stable

Custom Nodes, Packages, And Patches

Default custom nodes are defined in source\manifests\custom-nodes.json and installed instance-locally:

instances\<instance>\custom_nodes\

Current default nodes:

ComfyUI-Manager
CFZ-SwitchMenu
CFZ-Caching
ComfyUI-HFRemoteVae
ComfyUI-INT8-Fast-ROCM

The full install applies the rocm-performance profile from source\manifests\package-profiles.json.

Current performance packages:

triton-windows==3.7.1.post27
sageattention from a release wheel URL
bitsandbytes from a release wheel URL
flash-attn from a release wheel URL
amd-aiter from a release wheel URL

Package patches live in source\patches\sageattention\.

ComfyUI source patches live in source\patches\comfyui\ and are managed with:

.\rocmroll.bat patch list
.\rocmroll.bat patch list --instance rocm-stable
.\rocmroll.bat patch apply --instance rocm-stable
.\rocmroll.bat patch apply --instance rocm-stable --patch-id 001-avoid-comfyui-crashes-dynamic-vram
.\rocmroll.bat patch remove --instance rocm-stable --patch-id 001-avoid-comfyui-crashes-dynamic-vram

Launch Behavior

Generated launchers are written to:

launchers\<instance>.ps1
launchers\<instance>.bat

The launcher:

Uses the instance Python environment
Sets ROCm/HIP/PyTorch/Triton variables process-locally
Prepends environment and ROCm SDK paths to process PATH
Runs rocm-sdk.exe init when present
Uses shared input, output, and temp folders
Uses the instance extra_model_paths.yaml
Starts ComfyUI on 127.0.0.1:8188 unless another port is provided
Writes launch output to logs\launch

--user-directory is intentionally omitted because of a known ComfyUI database initialization issue. Use --shared-workflows to link workflows across instances:

.\rocmroll.bat instance install --name rocm-stable
.\rocmroll.bat instance repair --name rocm-stable

Creating symbolic links on Windows requires Developer Mode or an elevated PowerShell session.

State, Logs, Locks, And Cache

State files are JSON:

.state\runtimes\runtime-<version>.json
.state\environments\environment-<name>.json
.state\instances\instance-<name>.json
.state\global.json
.state\patches\

Install logs are written as both human-readable logs and JSONL:

logs\install\<yyyy-mm-dd>_<instance>_install.log
logs\install\<yyyy-mm-dd>_<instance>_install.jsonl

Show recent logs:

.\rocmroll.bat logs show

The full install/update pipeline uses an instance lock under .state\locks\. --force can override a stale install lock and requests forced recreation during full install/update.

Cache commands:

.\rocmroll.bat cache list
.\rocmroll.bat cache verify
.\rocmroll.bat cache clean --temp
.\rocmroll.bat cache clean --all
.\rocmroll.bat cache prune --older-than-days 30

cache clean --temp clears the temp folder and partial downloads. cache clean --all clears downloads, wheelhouse, Git cache, Triton cache, and temp. Running cache clean without flags removes partial downloads only.

ComfyUI Desktop Integration

If ComfyUI Desktop is installed and %APPDATA%\Comfy Desktop\installations.json exists, ROCmRoll registers or updates the installed instance there.

The Desktop integration:

Does nothing when ComfyUI Desktop is absent
Writes atomically
Reuses an existing Desktop ID on update
Removes the Desktop entry during full removal and when ComfyUI or environment components are removed
Stores the Desktop ID in instance state as comfyDesktopId
profile apply refreshes the Desktop entry with the applied profile's launchArgs and env

Troubleshooting

See TROUBLESHOOTING.md for known issues and solutions.

Start with diagnostics:

.\rocmroll.bat doctor --instance rocm-stable
.\rocmroll.bat doctor --system
.\rocmroll.bat doctor --gpu

Known ComfyUI database issue:

[ERROR] Failed to initialize database...
(sqlite3.OperationalError) unable to open database file

ROCmRoll works around this by omitting --user-directory from generated launchers. ComfyUI user data is written to the instance-local instances\<instance>\user\ folder. Use --shared-workflows when workflows should be shared.

Development Notes

Keep business logic in source\modules\*.psm1; keep batch files as thin wrappers. Major behavior changes should update the relevant module, manifest, template, README section, and docs/architecture.md.

Useful local checks:

.\rocmroll.bat help
.\rocmroll.bat doctor --system
.\rocmroll.bat doctor --gpu
.\rocmroll.bat doctor --instance rocm-stable --json

PowerShell parse check example:

$errors = $null
[System.Management.Automation.PSParser]::Tokenize((Get-Content .\source\rocmroll.ps1 -Raw), [ref]$errors) | Out-Null
$errors

See CONTRIBUTING.md for contribution guidelines.

Credits

ROCmRoll builds on the work of these projects and people:

License

MIT - see LICENSE.

Navigation Menu

Repository files navigation

ROCmRoll

Status

Requirements

Quick Start

Instance Overlays

Layout

Custom requirements

Custom nodes

Custom extra_model_paths.yaml

Declarative Instances

Channels

Automatic Channel Switching

Channel Migration

Profiles

Supported GPU Families

Exact GPU Chip Resolution (Multi-Arch Channels)

What Install Does

Project Layout

Configuration

Workspaces

Command Reference

Examples

Runtime And ROCm

Custom Nodes, Packages, And Patches

Launch Behavior

State, Logs, Locks, And Cache

ComfyUI Desktop Integration

Troubleshooting

Development Notes

Credits

License

About

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
profiles		profiles
source		source
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
FAQ.md		FAQ.md
LICENSE		LICENSE
README.md		README.md
TROUBLESHOOTING.md		TROUBLESHOOTING.md
logo.png		logo.png
rocmroll.bat		rocmroll.bat

Latest commit

History

Folders and files

Repository files navigation

ROCmRoll

Status

Requirements

Quick Start

Instance Overlays

Layout

Custom requirements

Custom nodes

Custom extra_model_paths.yaml

Declarative Instances

Channels

Automatic Channel Switching

Channel Migration

Profiles

Supported GPU Families

Exact GPU Chip Resolution (Multi-Arch Channels)

What Install Does

Project Layout

Configuration

Workspaces

Command Reference

Examples

Runtime And ROCm

Custom Nodes, Packages, And Patches

Launch Behavior

State, Logs, Locks, And Cache

ComfyUI Desktop Integration

Troubleshooting

Development Notes

Credits

License

About

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages