Gthulhu is a next-generation scheduler designed for the cloud-native ecosystem, built with Golang and powered by the qumun framework.

• The qumun provides a series of API and abstractions to facilitate the development of custom Linux kernel schedulers using eBPF and Go.
• Gthulhu implements a virtual runtime (vruntime) based scheduling policy, inspired by the concepts of proportional share scheduling and the needs of modern cloud-native applications.
• Gthulhu supports preemptive multitasking, latency-sensitive task prioritization, and dynamic time slice adjustment to optimize CPU utilization and responsiveness. User can define what kind of tasks should be prioritized by invoking HTTP based APIs, provided by the api server.

The name Gthulhu is inspired by Cthulhu, a mythical creature known for its many tentacles. Just as tentacles can grasp and steer, Gthulhu symbolizes the ability to take the helm and navigate the complex world of modern distributed systems — much like how Kubernetes uses a ship’s wheel as its emblem.

The prefix “G” comes from Golang, the language at the core of this project, highlighting both its technical foundation and its developer-friendly design.

Underneath, Gthulhu runs on the qumun framework (qumun means “heart” in the Bunun language, an Indigenous people of Taiwan), reflecting the role of a scheduler as the beating heart of the operating system. This not only emphasizes its central importance in orchestrating workloads but also shares a piece of Taiwan’s Indigenous culture with the global open-source community.

Click the image below to see our DEMO on YouTube!

To build and run Gthulhu, ensure you have the following prerequisites installed on your system

• Go 1.22+
• LLVM/Clang 17+
• libbpf
• Linux kernel 6.12+ with sched_ext support

See Installation guide for detailed installation instructions.

First, clone the required dependencies:

make dep
git submodule init
git submodule sync
git submodule update
cd scx
cargo build --release -p scx_rustland

This will clone libbpf and the custom libbpfgo fork needed for the project.

To ensure code quality, run the linter:

make lint

Build the scheduler with:

make build

This compiles the BPF program, builds libbpf, generates the skeleton, and builds the Go application.

Cross-compilation for arm64 is supported by setting the ARCH variable:

make build ARCH=arm64

To test the scheduler in a virtual environment using kernel v6.12.2:

make test

This uses vng (virtual kernel playground) to run the scheduler with the appropriate kernel version.

You can also test with a specific kernel version:

make test KERNEL_VERSION=6.13

Gthulhu is automatically tested for portability across multiple Linux kernel versions (6.12+) through a daily scheduled GitHub Actions workflow. This ensures that the released packages remain compatible with newer kernel versions. The portability tests run against kernel versions 6.12, 6.13, 6.14, 6.15, 6.16, and 6.17.

First, install schedctl from schedkit (created by @dottorblaster):

$ git clone https://github.com/schedkit/schedctl.git
$ cd schedctl
$ make install

Then, you can launch Gthulhu with:

$ sudo ./schedctl run gthulhu
Trying to pull ghcr.io/schedkit/gthulhu:latest...
Getting image source signatures
Copying blob sha256:a517a5a43837a7785dad62f579950a8abe4d1bd2ae5a096bda78150a1cc70c64
Copying blob sha256:2d35ebdb57d9971fea0cac1582aa78935adf8058b2cc32db163c98822e5dfa1b
Copying config sha256:85fb26cbfed25f79e321ef4e0a3e4e6fc7f01a957dbcee6aed815bdb93458136
Writing manifest to image destination
Storing signatures
Container ghcr.io/schedkit/gthulhu:latest started successfully
$ sudo podman ps -a
CONTAINER ID  IMAGE                            COMMAND     CREATED        STATUS            PORTS       NAMES
015d1b5fbe96  ghcr.io/schedkit/gthulhu:latest  /main       6 seconds ago  Up 6 seconds ago              gthulhu

To run the scheduler in a Docker container, you can either build locally or use the pre-built image from GitHub Container Registry:

Using the pre-built image from GitHub Packages:

docker run --privileged=true --pid host --rm ghcr.io/gthulhu/gthulhu:latest /gthulhu/main

Building locally:

make image
docker run --privileged=true --pid host --rm  127.0.0.1:25000/gthulhu:latest /gthulhu/main

If you need to inspect the BPF components, you can use:

sudo bpftool prog list            # List loaded BPF programs
sudo bpftool map list             # List BPF maps
sudo cat /sys/kernel/debug/tracing/trace_pipe # View BPF trace output

stress-ng -c 20 --timeout 20s --metrics-brief

See Installation guide.

This software is distributed under the terms of the GNU General Public License version 2.

See Contributing guide.

• NotebookLM: includes all of materials used in the project, including the pptx, design documents, and more.
• GitHub Discussion: a place for community discussions, questions, and feature requests.

• scx
• libbpfgo