Configure AI providers

The AI provider feature is a Technology Preview feature only. Technology Preview features might not be functionally complete. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

Register one or more AI providers in Che so that developers can select and use AI coding assistants when creating workspaces.

The AI tool registry is stored in a Kubernetes ConfigMap with specific labels. When the ConfigMap exists and contains at least one provider with a matching tool, the AI Selector widget is displayed on the dashboard. When the ConfigMap is absent or empty, the widget is hidden.

Che reads the node architecture of the cluster and filters the tool list before sending it to the dashboard. Tools whose arch list does not include the running architecture are hidden automatically. Tools that omit the arch field are shown on all architectures.

When a provider has multiple tool entries with different tag values, the AI Selector displays a version picker so developers can choose which image variant to inject.

Prerequisites

An active kubectl session with administrative permissions to the destination Kubernetes cluster. See Overview of kubectl.
The che-operator is installed and a eclipse-che custom resource exists in the eclipse-che namespace.

Procedure

Optional: Build and push a custom AI tool injector image.

The injector image is a container that carries the AI tool binary. During workspace startup, Che runs it as an init container to copy the binary into a shared volume. The following minimal Dockerfile is based on the OpenCode injector image:

FROM alpine:3.21 AS builder

ARG OPENCODE_VERSION=v1.2.27
ARG TARGETARCH

RUN apk add --no-cache curl tar gzip

RUN set -e && \
    case "${TARGETARCH}" in \
      amd64)   ARCH="x64" ;; \
      arm64)   ARCH="arm64" ;; \
      s390x)   ARCH="s390x" ;; \
      ppc64le) ARCH="ppc64le" ;; \
      *) echo "Unsupported architecture: ${TARGETARCH}" && exit 1 ;; \
    esac && \
    curl -fsSL -o /tmp/opencode.tar.gz \
      "https://github.com/anomalyco/opencode/releases/download/${OPENCODE_VERSION}/opencode-linux-${ARCH}.tar.gz" && \
    tar -xzf /tmp/opencode.tar.gz -C /tmp && \
    mv /tmp/opencode /usr/local/bin/opencode && \
    chmod +x /usr/local/bin/opencode

FROM registry.access.redhat.com/ubi10/ubi-minimal:10.0

COPY --from=builder /usr/local/bin/opencode /usr/local/bin/opencode-bin

RUN printf '#!/bin/sh\n\
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"\n\
OC_HOME="/tmp/opencode-home"\n\
mkdir -p "$OC_HOME/.config" "$OC_HOME/.local/share"\n\
export XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-$OC_HOME/.config}"\n\
export XDG_DATA_HOME="${XDG_DATA_HOME:-$OC_HOME/.local/share}"\n\
exec "$SCRIPT_DIR/opencode-bin" "$@"\n' > /usr/local/bin/opencode && \
    chmod +x /usr/local/bin/opencode

LABEL org.opencontainers.image.description="OpenCode CLI tool for DevWorkspace injection" \
      org.opencontainers.image.source="https://github.com/che-incubator/che-ai-tool-images.git"

Key design points:

Multi-stage build: the builder stage downloads the architecture-specific binary; the minimal runtime stage keeps the final image small.
Wrapper script: redirects XDG_CONFIG_HOME, XDG_DATA_HOME, and related variables to writable paths under /tmp, allowing the tool to run as an arbitrary UID on OpenShift.
Multi-arch: pass --platform to docker build to produce a multi-arch image. Include all architectures you want to support; see the arch field in the registry for the accepted values.

Build and push the image:
```
$ docker build --platform linux/amd64,linux/arm64,linux/s390x,linux/ppc64le \
    -t <your-registry>/<your-org>/opencode:next \
    --push .
```
See che-incubator/che-ai-tool-images for maintained injector image examples.

Create a registry.json file that defines providers, tools, and optional defaults:

{
  "providers": [
    {
      "id": "opencodeai/opencode",                       (1)
      "name": "OpenCode",
      "publisher": "opencode.ai",
      "description": "Open-source terminal AI coding agent supporting 75+ LLM providers.",
      "docsUrl": "https://opencode.ai",
      "icon": "https://example.com/opencode-icon.svg"
    }
  ],
  "tools": [
    {
      "providerId": "opencodeai/opencode",  (2)
      "tag": "next",                        (3)
      "name": "OpenCode",
      "url": "https://opencode.ai",
      "binary": "opencode",                 (4)
      "pattern": "init",                    (5)
      "injectorImage": "<your-registry>/<your-org>/opencode:next",  (6)
      "envVarName": "OPENAI_API_KEY",       (7)
      "arch": ["x86_64", "arm64"]           (8)
    },
    {
      "providerId": "opencodeai/opencode",
      "tag": "insiders",
      "name": "OpenCode",
      "url": "https://opencode.ai",
      "binary": "opencode",
      "pattern": "init",
      "injectorImage": "<your-registry>/<your-org>/opencode:insiders",
      "envVarName": "OPENAI_API_KEY",
      "arch": ["x86_64", "arm64", "s390x", "ppc64le"]  (9)
    }
  ],
  "defaultAiProviders": ["opencodeai/opencode"]  (10)
}

1	Unique provider identifier in `<vendor>/<product>` format.
2	Links the tool to its provider by `id`.
3	Version tag. When multiple tools share the same `providerId`, the dashboard shows a version picker so developers can choose which image variant to inject.
4	Binary name that must be available in `PATH` inside the workspace after injection.
5	Injection pattern: `init` copies a single binary into the shared volume; `bundle` copies a full runtime directory and creates a symlink.
6	Container image that carries the tool binary. Run as an init container at workspace start.
7	Environment variable name for the API key. The dashboard creates a Kubernetes Secret using this name as the data key.
8	Optional. List of node architectures on which this tool is available. Accepted values: `x86_64`, `arm64`, `s390x`, `ppc64le`. When omitted, the tool is shown on all architectures. The dashboard reads the cluster node architecture and hides tools whose `arch` list does not include the running architecture.
9	A second entry for the same provider with a different `tag` and broader `arch` support. On IBM Z (s390x) and Power (ppc64le) clusters, only this entry is shown because the `next` entry above excludes those architectures.
10	Optional. Provider IDs pre-selected in the AI Selector widget for new workspaces.

Create the ConfigMap in the eclipse-che namespace with the required labels:

$ kubectl create configmap ai-tool-registry \
  --from-file=registry.json=registry.json \
  -n eclipse-che \
  --dry-run=client -o yaml | \
  kubectl label --local -f - \
    app.kubernetes.io/component=ai-tool-registry \
    app.kubernetes.io/part-of=che.eclipse.org \
    -o yaml | \
  kubectl apply -f -

Verification

Open the Che dashboard.
Navigate to Create Workspace.
Verify that an AI Provider section is visible, listing the providers you configured.

To disable the AI Selector widget, delete the ai-tool-registry ConfigMap. Users will no longer see the AI Provider section on the Create Workspace page. Existing API key Secrets in user namespaces are not deleted automatically.

When you update the registry (for example, to remove a tool or change the injector image tag), existing workspaces are updated automatically before their next start. The dashboard removes stale tool injectors and replaces outdated image tags without user intervention.

Additional resources