kcoral 0.1.1

KCoral executes GPU benchmark programs over HTTP. It can also run as a CPU compilation service: upload code and data, call functions, and explicitly return the results you need.

Website · Documentation · Quickstart · Write a client program · KCoral Protocol

Install

Python 3.10 or newer is required. Install the prebuilt package from PyPI:

pip install kcoral

This installs the package with client dependencies. Use pip install "kcoral[server]" for both GPU execution and CPU compilation dependencies. See installation for source build and system requirements.

Run remote tools

export KCORAL_URL='http://127.0.0.1:8000'
kcoral run python --send experiment -- experiment/check.py
kcoral run compute-sanitizer --send experiment -- python experiment/check.py
kcoral run ncu --send experiment --out artifacts/ncu \
  -- --set basic --launch-count 1 -- python experiment/capture.py
kcoral run run-iket --send experiment --out artifacts/iket \
  -- profile --postprocess json -- python experiment/capture.py
kcoral run shell --send experiment -- bash experiment/setup.sh

Any remote tool also accepts --host HOST --port PORT, for example kcoral run python --host 127.0.0.1 --port 8000 --send experiment -- experiment/check.py. These options override KCORAL_URL, with a warning showing the address used.

See Builtin CLI Tools for common options and a separate guide to each tool, including dependencies, examples, and returned files.

Run the server

The server checks bubblewrap filesystem isolation at startup by default. If unavailable, it warns and runs without isolation. Use --sandbox none to disable it explicitly.

After installing the worker environment:

kcoral server --host 127.0.0.1 --port 8000

See deployment and configuration for CPU compilation, GPU selection, worker settings and limits.

File upload cache

File cache configuration covers the persistent cache directory, capacity and disabling caching.

Route across nodes

A Router accepts client requests and chooses an available compute node. Each node runs kcoral server --router URL --node-id NAME to start a supervisor that manages its Python server; both node processes connect outward to the Router. Clients use the same execution API.

See Router deployment for setup, scheduling and failure handling, and the Rust package guide for implementation and integration test commands.

Logs

Follow requests and worker events using the logging guide.

Python client

For simple tasks, use @client.function() and call .remote() to run a Python function on the server.

With a running GPU server, the first program uploads a tensor, adds one on the GPU, returns it and checks the values:

KCORAL_URL=http://127.0.0.1:8000 python examples/basics/first_program.py

See Your First Program, Write a client program and the Python API for the complete example and interfaces.

Use Program.return_file() or return_folder() to receive workspace outputs, then call .save(destination) on the result. See returning files and folders.

Protocol summary

Programs contain upload, get_function, run and return instructions. The protocol defines requests, results, caching and errors. Tutorials cover remote compilation, library uploads and separate compilation/execution servers.

Multi-GPU kernels and scripts

Use client.execute(program, gpu_count=N) to run a program on 1–8 GPUs. Single- and multi-GPU programs share the same worker and release GPUs for cpu_only calls. Both standalone examples execute through Program.run: one process controlling all GPUs and one worker per GPU. See the multi-GPU guide.