NVIDIA Run:ai: a GPU scheduling and governance layer on top of Kubernetes

Two components, and the traffic between them

Run:ai is made up of two components, both installed on a Kubernetes cluster, and understanding which is which clarifies most of the design.

The control plane provides centralized resource management, handles workload submission, and delivers cluster monitoring and analytics. It is the management layer: it connects to one or more Run:ai clusters and gives administrators and users a single place to operate across them.

The cluster component is a set of cluster services that provide enhanced scheduling and workload management on each Kubernetes cluster where workloads run. It extends Kubernetes native scheduling with Run:ai's GPU-aware capabilities.

The flow between them is the mechanism. Users and external systems interact with Run:ai through the web UI, the CLI or the REST API. The control plane manages workloads, organizational resources, policies and configuration across the connected clusters. Cluster services synchronize configuration and workload requests from the control plane to the appropriate cluster. Run:ai applies scheduling and resource policies to determine where and how workloads run on available GPU and compute resources. Workload and cluster status is then synchronized back to the control plane, providing centralized visibility across connected clusters.

So the control plane does not schedule, and the cluster services do not hold the global picture. The control plane owns policy and the cross-cluster view, the cluster component applies it locally, and status flows back. That split is what allows a single place to operate across several clusters without centralizing the scheduling decision itself.

The primary language is Go, the licence is Apache-2.0, the default branch is main, and the documentation lives at docs.nvidia.com/run-ai. The recent releases are 3.0.20 on 2026-10-11, 3.0.19 on 2026-10-08 and 3.0.18 on 2026-10-07, and the last push was on 2026-10-22.

What the GPU scheduling actually does

The capabilities table is the substantive part of the readme, and the scheduling row is where most of the value sits.

AI-aware GPU scheduling schedules GPU workloads using fair-share, preemption, bin-packing, priorities and topology-aware placement. That list is five distinct policies rather than one feature. Fair-share means a team's quota is a share of the estate rather than a fixed set of devices, which matters when the estate is a mixed set of card models. Preemption means a higher-priority job can take a GPU from a running one, which is what makes a shared cluster feel responsive. Bin-packing is about utilisation, filling a node's cards before spreading across nodes. Priorities give an ordering among workloads. Topology-aware placement puts a multi-GPU job on a machine whose cards are connected the way the job needs.

Dynamic GPU allocation shares GPU resources across workloads with fractional GPU allocation and dynamic use of available capacity. Fractional allocation lets a card be split between workloads rather than reserved whole, which is the difference between a cluster that is fully booked and one where a second team is told to wait.

Resource quotas and policies allocate GPU resources across departments and projects and enforce organizational resource policies. Multi-cluster management centrally manages workloads, resources and configuration across multiple Kubernetes clusters. AI workload management handles workspaces, training, distributed training and inference, with extensible support for additional Kubernetes workloads. Access control and governance controls access to Run:ai resources with role-based permissions and enforces organizational policies across workloads and resources. Monitoring and observability provides visibility into clusters, nodes, GPUs, workloads, resource utilization and platform activity. Multiple interfaces means the web UI, the CLI and the REST API.

The word governance appears in three of those rows, and it is the part that has no equivalent in plain Kubernetes. A quota in Kubernetes is a namespaced limit on requests and limits for a set of resources, checked at admission. What a shared GPU estate usually needs is a hierarchy of quotas that reflect how an organisation is actually structured, departments above projects, and a scheduler that treats a department's share as something to be honoured over time rather than a ceiling to be checked at admission time.

The scheduler that does the work, and the tools it does not replace

The section on how Run:ai relates to other tools is unusually careful about boundaries, and it is the best guide to whether you need this at all.

On cluster orchestration, Run:ai runs on Kubernetes and OpenShift rather than replacing them, extending the cluster with GPU-aware scheduling rather than replacing native scheduling. On schedulers, it ships the KAI Scheduler and adds fair-share, preemption, fractional GPUs and quota hierarchies across departments and projects. On GPU enablement, the NVIDIA GPU Operator and Network Operator are complementary: they expose and configure GPUs on the nodes, while Run:ai decides which workloads get them and for how long.

On ML platforms and pipelines, Kubeflow, Ray, Argo Workflows and Slurm are complementary for the Kubernetes-based ones. They submit workloads, Run:ai schedules and governs the GPU capacity those workloads consume. Slurm is named as an alternative for HPC-style batch on bare metal, which is a useful signal about where Run:ai is not trying to go.

On workload types, Run:ai integrates with the Training Operator, LeaderWorkerSet, Knative and KServe to manage workspaces, training, distributed training and inference as first-class workloads.

The KAI Scheduler is the piece most adopters will care about, because it is a separate project under its own repository and it is what actually places pods. The readme's framing is that Run:ai adds the organisational layer on top of it: fair-share over time, preemption between teams, fractional cards, and quota hierarchies. The distinction is worth holding because it means part of the scheduling behaviour lives outside this monorepo and will be versioned separately.

The sentence that closes the section is the decision rule. If you need GPU sharing, quota enforcement and multi-tenant governance across teams sharing one Kubernetes GPU estate, that is the gap Run:ai fills. If you only need to run a single team's jobs on dedicated GPUs, native Kubernetes scheduling may be sufficient.

That is the honest boundary, and it is stated by the project rather than inferred.

What the monorepo contains, and how it is built

The repository is large and structured as a monorepo, and the top-level layout is a map of the product.

The control-plane/ directory holds the control plane services. runai-cluster/ holds the in-cluster services. runai-installer/ is the installer, runai-clients/ holds shared client packages, runai-common-packages/ holds the shared libraries, and runai-common-chart/ is the shared Helm chart. There are also runai-application-packages/ for application-level resources, runai-mcp-server/ for the MCP server, and common/ for code shared across the whole tree.

Two directories tell you something about the maturity of the project. scale-load/ and scale-tests/ exist, which means the team runs load tests rather than assuming capacity, and designs/ holds design documents, which is the sign of a project that writes things down before writing the code. There is a docs/ directory, a fern/ directory for the API documentation tooling, a tools/ directory, a skills/ directory, and a build/ directory.

The local development environment is described in local-dev.md with a local-dev.sh script, and the .local-dev/ directory is at the top level, so a contributor can run the control plane and the cluster services locally rather than against a cluster. An .agents/ directory and a .claude/ directory sit alongside a CLAUDE.md and an AGENTS.md, which indicates that automated coding assistants are an expected part of the workflow, and a .coderabbit.yaml suggests an automated code review service is wired in too.

The release and governance scaffolding is extensive. CHANGELOG.md, RELEASE.md, CODEOWNERS, MAINTAINERS.md, GOVERNANCE.md, SECURITY.md, SUPPORT.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, NOTICE, COPYRIGHT and TRADEMARKS.md are all present, plus an artifact-metadata.json for release metadata and a renovate.json for dependency updates. There is a .nspect-vuln-allowlist.toml and a .security-triage.yaml, and an .oss-export-id for export compliance.

The Makefile in the repository root is not the build entry point. Its build, test and lint targets each echo NA, and the only implemented target is validate, which runs a Python script to check that the CODEOWNERS file is consistent. The actual build is somewhere else, and this Makefile is the guard rail for the ownership map rather than a build system.

Where to get it, and what to check before you commit

The distribution model has an unusual shape that is worth understanding before an evaluation.

The readme describes the platform as open-source, and the licence is Apache-2.0, which is permissive and imposes no obligation on users of the software beyond attribution and preservation of the licence and copyright notices. The README links an API Reference at docs.nvidia.com/run-ai/self-hosted/reference/home and a Documentation section with a Getting Started architecture page. There is a Roadmap section in the readme itself, and the installation section and the CONTRIBUTING.md are both linked from the header.

What the readme does not spell out, and what you will need to find out, is how the software is obtained in practice. The repository is under the dsx-ai-factory organisation, the artefacts are hosted under NVIDIA's documentation site, and the image publication model is not described in this readme. That is the first thing to establish, because a platform you cannot pull is not an evaluation candidate.

The second thing to check is the version line. The recent releases are all in the 3.0.x range with dates in October 2026, and the last push came after them, so the tree is ahead of the newest tag. For a control plane that manages GPU estates across teams, that distinction matters: you want to know whether the components in your cluster match the control plane version, because the readme describes configuration and workload requests being synchronized between the two.

The third check is the honest scoping question. Run:ai does not replace Kubernetes, a container runtime or a CI/CD system, so an adoption that expects it to be a complete platform will find gaps it was not designed to fill. The evaluation should be: take a cluster with two or three teams already fighting over GPUs, install the cluster component and the KAI Scheduler, and see whether fair-share and preemption behave the way the readme describes. That test answers the question the readme itself poses, and it is cheaper than reading the whole documentation set.

If the answer is yes, the rest of the product surface, workspaces, distributed training, inference serving through KServe and Knative, multi-cluster management and the MCP server, is where the platform earns its keep over time.

validate:
	@echo "Validating CODEOWNERS..."
	@python3 .github/scripts/validate-codeowners.py CODEOWNERS
	@echo "CODEOWNERS validation completed successfully"

Running that validation is what the repository's own make target does, and it is the one target that is not a placeholder.

Editorial conclusion

Run:ai fits an organisation with several teams and departments contending for a shared Kubernetes GPU estate, where fair-share, quota hierarchies and preemption are operational requirements rather than aspirations. It does not fit a single team with dedicated GPUs, since the readme says native Kubernetes scheduling may be sufficient there, and it does not replace a container runtime, a CI/CD system or a scheduler such as Volcano or Kueue. Before deploying, read the architecture overview for the control plane and cluster split, and check the KAI Scheduler that Run:ai ships, because that is the component doing the actual placement decisions inside your cluster.

Frequently asked questions

Official sources

1. dsx-ai-factory/run-ai on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases