KernelFoundry

KernelFoundry is a toolkit for hardware-aware GPU kernel optimization, targeting SYCL, OpenCL and CUDA with a focus on Intel GPUs.

The simplest way to use KernelFoundry is its MCP server and custom agent. From your usual coding IDE, install the KF agent and tools and point the agent at a slow GPU kernel. The agent isolates the kernel, builds a reference implementation to beat, finds your existing tests or writes new ones, and derives benchmark sizes from how the code is actually called — asking you only about what it can't work out on its own.

From there, KernelFoundry generates, compiles, benchmarks and profiles candidate kernels on real hardware, keeping the fastest ones that still pass those tests. On KernelBench it reaches 2.3x geometric-mean speedup for SYCL (paper).

_{A coding agent turns the input into a task package of reference, kernel-wrapper and tests, which you can also author yourself. The task package enters an optimization loop, driven either by (A) the evaluation tool in a modify-and-test cycle or (B) an evolutionary algorithm searching for the best kernel autonomously. The loop generates, compiles, benchmarks on a real GPU and profiles candidates, feeding test results, runtime stats and profiler feedback back into generation, and emits an optimized kernel to integrate back into your code.}

Core concepts

• Task: one kernel you want to speed up, defined by a reference implementation plus tests.
• Job: one run of the optimization on a task. A task can have many jobs.
• Task package: the folder KernelFoundry evaluates: kernel file, reference, tests, and config.yaml. The agent builds it for you, or you write it yourself. See Anatomy of a task package for the full specification.
• EVOLVE block: the part of the kernel code that is modified in the optimization loop, marked [EVOLVE_START] / [EVOLVE_END]. Everything outside it (e.g. tests) is left untouched at that point.

Quick start with Dev Container

The fastest way to set up KernelFoundry is by cloning the example repository, which comes with a dev container configuration with dependencies preinstalled for Intel GPU development. Click on the badge to clone the example; VS Code then offers to reopen it in the container.

Requires a Linux host system with Intel GPU drivers, Docker, and VS Code with the Dev Containers extension.

Getting started

Running KernelFoundry requires a GPU and a working toolchain for your GPU vendor, plus an optional profiler. Expand this section for the full toolchain setup.

# Download and add the Intel GPG key
wget -O- https://apt.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS.PUB | \
  gpg --dearmor | sudo tee /usr/share/keyrings/oneapi-archive-keyring.gpg > /dev/null

# Add the Intel oneAPI repository
echo "deb [signed-by=/usr/share/keyrings/oneapi-archive-keyring.gpg] https://apt.repos.intel.com/oneapi all main" | \
  sudo tee /etc/apt/sources.list.d/oneAPI.list

# Install the oneAPI toolkit and VTune
sudo apt update && sudo apt install -y \
    intel-oneapi-base-toolkit-2025.2 \
    intel-oneapi-vtune=2026.1.0-13

# Source the Intel environment (needed in every new shell)
source /opt/intel/oneapi/setvars.sh

git clone https://github.com/intel/pti-gpu.git
pushd pti-gpu/tools/unitrace
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_WITH_MPI=OFF ..
make
popd

# Allow non-root profiling
if [ -f /proc/sys/dev/i915/perf_stream_paranoid ]; then
    sudo sh -c 'echo 0 > /proc/sys/dev/i915/perf_stream_paranoid'
fi
if [ -f /proc/sys/dev/xe/observation_paranoid ]; then
    sudo sh -c 'echo 0 > /proc/sys/dev/xe/observation_paranoid'
fi

if [ -f /proc/sys/kernel/kptr_restrict ]; then
    sudo sh -c 'echo 0 > /proc/sys/kernel/kptr_restrict'
fi

Install KernelFoundry with MCP server

When the GPU and toolkit are installed, create a virtual environment and install Python 3.12 and KernelFoundry.

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# On Windows: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
source $HOME/.local/bin/env

# Create and activate a virtual environment with Python 3.12
uv venv --python 3.12
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install pip

# install kernelfoundry mcp
pip install 'kernelfoundry[mcp,algo]'

Then, use our helper script to create the MCP server config:

python -m kernelfoundry.mcp_server create_config   # prompts for a few answers, writes an MCP client config

This script will output the MCP config file, which you can copy-paste when adding the MCP server to your coding agent (GitHub Copilot, Claude Code, Cursor). Note: create_config is interactive: it asks a few questions and writes the client config from the answers. It has no non-interactive mode, so it cannot be scripted or run by an agent as-is.

Using KernelFoundry via the MCP server

Point the agent to agent-workflow.md to instruct it how to use KernelFoundry.

A typical prompt is the following (fill in dependent on your use case):

Optimize <function> in <file path or upstream URL> for GPU with KernelFoundry (see <path/to/agent-workflow.md> for instruction how to use KernelFoundry).
# Optional (the agent will infer or ask if omitted):
# Language: <SYCL | OpenCL | CUDA | triton>
# Benchmark shapes: <e.g. from upstream tests, or specific sizes>
# Build: <command>   Test: <command> 
# Constraints: <e.g. preserve macro-driven runtime flexibility>

The agent creates the task package (i.e. code for testing the kernel in isolation), validates it, runs the optimization loop and reports the speedup. Full walkthrough: Optimize a kernel with a coding agent.

Running the algorithm via the CLI

Install requirements

Create uv environment:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

# Create and activate a virtual environment with Python 3.12
uv venv --python 3.12
source .venv/bin/activate
uv pip install pip

Pip install KernelFoundry: (Note: pip installing gives you the algorithm CLI, MCP server and the results UI for running KernelFoundry on custom tasks. Clone instead if you want the KernelBench task set, which is data and does not ship in the package.)

pip install 'kernelfoundry[all]'

Options: [all], [algo] (to execute the algorithm from CLI), [mcp] (only mcp server dependencies, cannot execute locally unless algo is installed), and [ui] (gui for viewing KF results).

Or install from source:

# Install all dependencies from clone
git clone https://github.com/isl-org/kernelfoundry.git
cd kernelfoundry
uv pip install -e .[all]

Install torch:

Torch is NOT a requirement for running KernelFoundry; it is only required if the task package is using torch tensors, e.g. to move data to the GPU. However, it is needed for KernelBench examples.

# Install torch. Intel GPUs (XPU wheels):
python -m pip install torch==2.9 torchvision==0.24 torchaudio==2.9.0 --index-url https://download.pytorch.org/whl/xpu
# NVIDIA GPUs instead:
python -m pip install torch==2.13.0 --index-url https://download.pytorch.org/whl/cu130

Configuring the LLM API

The algorithm runs an evolutionary search autonomously, rather than step by step with an agent. The generation step calls an LLM API. Set the key for your provider:

export OPENAI_API_KEY=...      # server_type: openai
export ANTHROPIC_API_KEY=...   # server_type: anthropic

Choose the model and provider in kernelfoundry/configs/inference/server.yaml. Any model your provider offers works; model_name is passed straight through.

Run the optimization algorithm

Two examples are provided within the repo. Running them requires cloning the repo instead of pip installing it, so that the task files are found. Both of them require a torch installation in the unit tests.

# Optimize a KernelBench task 
python -m kernelfoundry.algorithm run task=19_ReLU task_origin=KernelBench \
    job_name=my_experiment gpu_arch=lnl language=SYCL

# Optimize your own task
python -m kernelfoundry.algorithm run task=tasks/example_custom task_origin=custom \
    job_name=my_custom_experiment gpu_arch=lnl language=SYCL

Configuring a job

You can configure the optimization algorithm in the config.yaml file of your job. Common parameters are:

See Config Parameters for a full list.

Target hardware

gpu_arch and language must agree: a CUDA architecture requires language: CUDA. Both accept a comma-separated list to benchmark on several targets.

Results and monitoring

Every candidate is recorded, including the ones that fail: the prompt, the model's answer, the measured runtimes and the evaluation log. Nothing measured gets thrown away.

Generated kernels, jobs and metrics are stored in a SQLite database, by default runs/kernels.sqlite3 relative to where you started the run. Change it with paths.kernels_db_path.

When the MCP server runs in local execution mode under VS Code, the database is written relative to your home directory, because that is where the editor launches the server from.

Browse results in the web UI:

python -m kernelfoundry.gui

It serves http://localhost:8885 and shows:

• Job logs and execution monitoring
• Kernel performance metrics and comparisons
• Optimization progress visualization
• Roofline analysis and performance profiling
• Generated kernel source and metadata

Troubleshooting

Documentation

Full documentation, including the user guide and API reference, is at isl-org.github.io/kernelfoundry/docs.

This README covers deciding, installing and getting a first run. The guide covers everything after that:

To build the docs locally:

pip install .[docs]
cd docs
make html          # output in docs/_build/html/

Contributing

Bug reports and pull requests are welcome via GitHub issues. Code is formatted with black (line length 120) and checked in CI.

License

Apache License 2.0. See LICENSE.

Citation

If you use KernelFoundry in your research, please cite:

@inproceedings{wiedemann2026kernelfoundry,
  title={KernelFoundry: Hardware-aware evolutionary GPU kernel optimization},
  author={Wiedemann, Nina and Leboutet, Quentin and Paulitsch, Michael and Wofk, Diana and Ummenhofer, Benjamin},
  booktitle={Proceedings of the 41st International Conference on Machine Learning (ICML 2026)},
  year={2026}
}