Skip to content
OpenCharly

rocm

Recipe card from the charly-distros plugin (Images — the deployable catalog).

rocm – AMD ROCm runtime and OpenCL

Section titled “rocm – AMD ROCm runtime and OpenCL”

Candy Properties

Section titled “Candy Properties”
Property Value
Install files charly.yml

Environment Variables

Section titled “Environment Variables”
Variable Value
ROCM_PATH /usr

Runtime Environment (auto-detected)

Section titled “Runtime Environment (auto-detected)”
Variable Source Example
HSA_OVERRIDE_GFX_VERSION KFD topology sysfs 10.3.0 (RDNA2), 11.0.0 (RDNA3)
DRINODE DRM render node enumeration /dev/dri/renderD128 (typical), /dev/dri/renderD129 (multi-GPU)

Both variables are not baked into the candy — they are auto-detected from host state at runtime and injected as container environment variables via appendAutoDetectedEnv() in candy/plugin-deploy-pod/config_setup_helpers.go (relocated wholesale from charly-core’s charly/devices.go in the 2026-07-22 dead-code-radical-removal batch). The same function is called by charly config, charly start, and charly shell (via that candy’s own config_setup.go / resolve.go / resolve_f12.go resolvers), so interactive shells and deployed services see the identical env set.

  • HSA_OVERRIDE_GFX_VERSION is read from /sys/class/kfd/kfd/topology/nodes/*/properties (gfx_target_version field).
  • DRINODE is selected by walking /dev/dri/renderD* and picking the node that matches the AMD PCI device exposed to the container.

Override either with -e HSA_OVERRIDE_GFX_VERSION=X.Y.Z or -e DRINODE=/dev/dri/renderD129. See /charly-core:charly-doctor (Hardware Detection) for how the probe runs on the host side, and /charly-distros:nvidia (DRINODE Auto-Injection) for the NVIDIA counterpart using the same mechanism.

Security

Section titled “Security”
security:
  group_add:
    - keep-groups

Uses keep-groups to preserve host supplementary groups (video, render) inside the container. This is the standard approach across all candies – Podman’s keep-groups is mutually exclusive with explicit group names.

Packages

Section titled “Packages”

RPM (Fedora system repos): rocm-hip-runtime, rocm-opencl, rocm-clinfo, rocm-smi

Host Requirements

Section titled “Host Requirements”

AMD GPU support requires:

  1. /dev/kfd device (auto-detected by charly)
  2. /dev/dri/renderD* render nodes (auto-detected)
  3. User in video and render groups (charly udev status to check)
  4. amdgpu kernel driver loaded

Run charly doctor to verify detection. Run charly udev install to set up device permissions.

Usage

Section titled “Usage”
# charly.yml -- standalone AMD GPU image
my-amd-app:
  base: fedora
  candy:
    - rocm
    - my-app

Verification

Section titled “Verification”
Terminal window
# Check AMD GPU detected on host
charly doctor | grep "AMD GPU"


# Verify inside container
charly shell my-amd-app -c "clinfo --list"
charly shell my-amd-app -c "rocm-smi"
charly shell my-amd-app -c "echo \$HSA_OVERRIDE_GFX_VERSION"
Section titled “Related Candies”
Section titled “Related Commands”

Used In Boxes

Section titled “Used In Boxes”

Not directly used in any current box definition. Available as a standalone candy for AMD GPU support. The NVIDIA base image (/charly-distros:nvidia) is the currently-shipped GPU box; an AMD counterpart can be composed by substituting this candy.

When to Use This Skill

Section titled “When to Use This Skill”

Use when the user asks about:

  • AMD GPU support in containers
  • ROCm, HIP, or OpenCL setup
  • /dev/kfd device access
  • HSA_OVERRIDE_GFX_VERSION configuration
  • AMD GPU passthrough or compute
  • The rocm candy or AMD GPU computing
  • Comparing AMD vs NVIDIA GPU support
Section titled “Related”
  • /charly-image:layer — candy authoring reference (charly.yml schema, task verbs, service declarations)
  • /charly-check:check — declarative testing (check: block, charly check box, charly check live)