Skip to main content
Workbench image configuration can be customized at the control plane level (available for customers using TrueFoundry in a separately hosted control plane only). This customization allows you to override the default TrueFoundry workbench images with images from your private registry — useful when your cluster cannot pull from the public TrueFoundry registry, or when you want to pre-bake additional dependencies into your images.

​
How do workbench images work?

When a user launches a notebook or SSH server from the TrueFoundry workbench, the platform presents a list of available environment images. Each image entry has:
  • type — either notebook (Jupyter Lab) or ssh-server
  • name and description — shown to users in the image picker
  • image — a list of match rules that resolve to an image_uri. The match field allows you to serve different image variants based on node selectors or other criteria. An empty match: [] means the spec applies unconditionally.
The default images are supplied by TrueFoundry. You can override them entirely by providing your own list under workbenchImages in the tfy-configs section of the truefoundry helm chart.

​
How to customize workbench images for your Control Plane?

You need to update the truefoundry helm chart values with your desired image list under tfy-configs.configs.workbenchImages. Each image entry requires:
  • name — display name shown in the workbench UI
  • type — notebook or ssh-server
  • enabled — set to true to show the image in the picker
  • description — brief description shown to users
  • image — list of match/spec pairs; use match: [] for an unconditional default
tfy-configs:
  configs:
    workbenchImages: |
      images:
        - name: Jupyter Lab Minimal Image
          type: notebook
          enabled: true
          description: Minimal image with Python 3.10 environment. Starts quickly
          image:
            - match: []
              spec:
                image_uri: 'your-registry.example.com/tfy-images/jupyter:0.3.10-py3.10.15-sudo'
        - name: Jupyter Lab Minimal Image
          type: notebook
          enabled: true
          description: Minimal image with Python 3.12 environment. Starts quickly
          image:
            - match: []
              spec:
                image_uri: 'your-registry.example.com/tfy-images/jupyter:0.4.3-py3.12.11-sudo'
        - name: Jupyter Lab Cuda 12.1 Image
          type: notebook
          enabled: true
          description: Python 3.10 environment with cuda toolkit 12.1
          image:
            - match: []
              spec:
                image_uri: 'your-registry.example.com/tfy-images/jupyter:0.3.10-cu121-py3.10.15-sudo'
        - name: Jupyter Lab Cuda 12.4 Image
          type: notebook
          enabled: true
          description: Python 3.12 environment with cuda toolkit 12.4
          image:
            - match: []
              spec:
                image_uri: 'your-registry.example.com/tfy-images/jupyter:0.4.3-cu124-py3.12.11-sudo'
        - name: SSH Server Minimal Image
          type: ssh-server
          enabled: true
          description: SSH Server image with Python 3.10 environment
          image:
            - match: []
              spec:
                image_uri: 'your-registry.example.com/tfy-images/ssh-server:0.3.10-py3.10.15'
        - name: SSH Server Minimal Image
          type: ssh-server
          enabled: true
          description: SSH Server image with Python 3.12 environment
          image:
            - match: []
              spec:
                image_uri: 'your-registry.example.com/tfy-images/ssh-server:0.4.3-py3.12.11'
        - name: SSH Server Cuda 12.1 Image
          type: ssh-server
          enabled: true
          description: Python 3.10 environment with cuda toolkit 12.1
          image:
            - match: []
              spec:
                image_uri: 'your-registry.example.com/tfy-images/ssh-server:0.3.10-cu121-py3.10.15'
        - name: SSH Server Cuda 12.4 Image
          type: ssh-server
          enabled: true
          description: Python 3.12 environment with cuda toolkit 12.4
          image:
            - match: []
              spec:
                image_uri: 'your-registry.example.com/tfy-images/ssh-server:0.4.3-cu124-py3.12.11'