Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Deepak-Sangle/TornadoVM/llms.txt

Use this file to discover all available pages before exploring further.

Docker containers give you a reproducible, dependency-free environment for running TornadoVM workloads — no manual driver installation, no JDK version mismatches. The TornadoVM team maintains pre-built images on Docker Hub under the beehivelab organization, covering NVIDIA GPUs and Intel Integrated Graphics with both OpenJDK and GraalVM runtimes. Because containers isolate the filesystem but not the kernel, GPU access requires passing the physical device through from the host; NVIDIA and Intel each have their own mechanism for doing so.

​
Available Official Images

All official TornadoVM images are published at https://github.com/beehive-lab/docker-tornado and pulled from Docker Hub under the beehivelab namespace.

NVIDIA + OpenJDK 17

beehivelab/tornadovm-nvidia-openjdk:latestLatest TornadoVM for NVIDIA GPUs, based on OpenJDK 17.

NVIDIA + GraalVM

beehivelab/tornadovm-nvidia-graalvm:latestLatest TornadoVM for NVIDIA GPUs, based on GraalVM JDK 17.

Intel iGPU + OpenJDK 17

beehivelab/tornadovm-intel-openjdk:latestTornadoVM for Intel Integrated Graphics and Intel CPUs via OpenCL.

Intel iGPU + GraalVM

beehivelab/tornadovm-intel-graalvm:latestTornadoVM for Intel Integrated Graphics, based on GraalVM JDK 17.
Images have been tested on CentOS ≥ 7.4 and Ubuntu ≥ 16.04. All images include the docker-tornado runner scripts that wrap the tornado command for convenience.

​
NVIDIA GPU Setup

​
Prerequisites: NVIDIA Container Toolkit

NVIDIA GPU passthrough requires the NVIDIA Container Toolkit (formerly nvidia-docker2) to be installed on the host machine. This registers a custom Docker runtime (nvidia) that exposes GPU devices inside containers.
1

Install NVIDIA Container Toolkit on the host

Follow the official guide at https://github.com/NVIDIA/nvidia-docker for your Linux distribution. After installation, verify with:
docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi
You should see your GPU listed in the nvidia-smi output.
2

Pull the TornadoVM NVIDIA image

docker pull beehivelab/tornadovm-nvidia-openjdk:latest
Or for the GraalVM variant:
docker pull beehivelab/tornadovm-nvidia-graalvm:latest
3

Clone the docker-tornado runner scripts

The docker-tornado repository contains convenience scripts that mount your working directory and forward the GPU:
git clone https://github.com/beehive-lab/docker-tornado
cd docker-tornado
4

Run a TornadoVM example

Use the provided runner script to execute the bundled Matrix Multiplication example:
./run_nvidia_openjdk.sh tornado \
  -cp example/target/example-1.0-SNAPSHOT.jar \
  example.MatrixMultiplication
Expected output:
Computing MxM of 2048x2048
    CPU Execution: 0.36 GFlops, Total time = 48254 ms
    GPU Execution: 277.09 GFlops, Total Time = 62 ms
    Speedup: 778x

​
Intel Integrated Graphics Setup

1

Prerequisites: Intel OpenCL Driver

The beehivelab/tornadovm-intel-openjdk image requires the Intel OpenCL compute runtime to be accessible. More information: https://github.com/intel/compute-runtime.
2

Pull the Intel image

docker pull beehivelab/tornadovm-intel-openjdk:latest
Or with GraalVM:
docker pull beehivelab/tornadovm-intel-graalvm:latest
3

Run an example

git clone https://github.com/beehive-lab/docker-tornado
cd docker-tornado

./run_intel_openjdk.sh tornado \
  -cp example/target/example-1.0-SNAPSHOT.jar \
  example.MatrixMultiplication --parms="256"
Expected output:
Computing MxM of 256x256
    CPU Execution: 1.53 GFlops, Total time = 22 ms
    GPU Execution: 8.39 GFlops, Total Time = 4 ms
    Speedup: 5x

​
Common Container Options

The tornado command inside the container is an alias for java with all TornadoVM flags pre-configured. You can pass any standard Java or TornadoVM option through it. 
./run_nvidia.sh tornado --printKernel \
  example/MatrixMultiplication

​
Building a Custom TornadoVM Docker Image

If you need a custom build — for example, a specific backend combination or a different JDK version — you can extend one of the official base images. 
# Extend the official NVIDIA + OpenJDK image
FROM beehivelab/tornadovm-nvidia-openjdk:latest

# Set working directory
WORKDIR /app

# Copy your application JAR
COPY target/myapp-1.0.jar /app/myapp.jar

# Set environment variables
ENV TORNADOVM_HOME=/usr/local/tornadovm
ENV PATH="${TORNADOVM_HOME}/bin:${PATH}"
ENV LD_LIBRARY_PATH="${TORNADOVM_HOME}/bin/sdk/lib:${LD_LIBRARY_PATH}"

# Default command
CMD ["tornado", "-cp", "/app/myapp.jar", "com.example.MyKernel"]
Build and run: 
docker build -t my-tornadovm-app .
docker run --rm --gpus all my-tornadovm-app

​
Key Environment Variables Inside Containers

VariablePurposeTypical Value
TORNADOVM_HOMERoot of the TornadoVM installation/usr/local/tornadovm
JAVA_HOMEJDK used by TornadoVM/usr/local/tornadovm/etc/dependencies/TornadoVM-graal-jdk-21/...
PATHMust include $TORNADOVM_HOME/bin/sdk/binSet in setvars.sh
LD_LIBRARY_PATHNative GPU backend libraries$TORNADOVM_HOME/bin/sdk/lib
TORNADO_SDKPath to the SDK directory$TORNADOVM_HOME/bin/sdk

​
Limitations of Containerized GPU Access

GPU passthrough in Docker is not as seamless as bare-metal access. Be aware of the following constraints:
  • Driver version coupling: The NVIDIA driver version inside the container must be compatible with the driver installed on the host. Mismatches cause runtime failures.
  • No GPU virtualisation: Docker does not virtualise GPUs. The --gpus flag exposes a real physical device — if another container or the host process is using it, you may see contention.
  • Intel iGPU device files: Intel integrated GPU access typically requires passing /dev/dri device files with --device=/dev/dri and adding the container user to the video group.
  • OpenCL ICD loader: The container must have the OpenCL ICD loader (libOpenCL.so) and a valid .icd file in /etc/OpenCL/vendors/. The official images handle this, but custom images must replicate it.
  • Metal (macOS) not supported: Apple’s Metal backend cannot run inside Linux Docker containers; it requires macOS with Apple Silicon or AMD GPU hardware.

Build docs developers (and LLMs) love

Get started for freeTalk to us