krayne 0.1.0

CLI and SDK for creating, managing, and scaling Ray clusters on Kubernetes

Krayne

CLI and SDK for creating, managing, and scaling Ray clusters on Kubernetes.

Krayne wraps the KubeRay operator behind a clean, opinionated interface so ML practitioners can get distributed compute without touching Kubernetes manifests.

Quickstart

pip install krayne

Create a Ray cluster with a single command:

krayne create my-cluster --gpus-per-worker 1 --workers 2

Or use the Python SDK to define code and infrastructure together:

import ray
from krayne.api import managed_cluster
from krayne.config import ClusterConfig, WorkerGroupConfig

config = ClusterConfig(
    name="hello-world",
    worker_groups=[WorkerGroupConfig(replicas=2)],
)

with managed_cluster(config) as managed:
    ray.init(managed.tunnel.client_url)     # ray://localhost:... (tunneled)

    @ray.remote
    def hello(x):
        return f"Hello from worker, {x}!"

    futures = [hello.remote(i) for i in range(4)]
    print(ray.get(futures))

    ray.shutdown()
# Tunnels closed, then cluster deleted

Tunnels are opened by default — access the dashboard, notebook, and other services via localhost:

from krayne.api import managed_cluster
from krayne.config import ClusterConfig

config = ClusterConfig(name="my-cluster")

with managed_cluster(config) as managed:
    # Tunnel (localhost) URLs via managed.tunnel
    print(managed.tunnel.dashboard_url)  # http://localhost:...
    print(managed.tunnel.client_url)     # ray://localhost:...

    # In-cluster IPs via managed.cluster
    print(managed.cluster.dashboard_url) # http://10.0.0.1:8265
# Tunnels closed, then cluster deleted

Features

• Zero-config defaults — every command works with no flags. Sensible defaults get you a working cluster instantly.
• CLI and SDK — the CLI is a thin shell over the Python SDK. Anything you do from the terminal, you can do from code.
• Functional API — stateless free functions, not class hierarchies. Easy to test, easy to compose.
• Pydantic config — validated configuration with YAML override support. No silent failures.
• Rich output — beautiful terminal tables via Rich, with --output json for scripting.

CLI Overview

krayne create <name>      Create a new Ray cluster
krayne get                List clusters in a namespace
krayne describe <name>    Show detailed cluster info
krayne scale <name>       Scale a worker group
krayne delete <name>      Delete a cluster

All commands support -n/--namespace, --output json, and --debug flags.

Documentation

Full documentation is available at the Krayne docs site.

• Getting Started
• CLI Reference
• Python SDK Reference
• Configuration
• Architecture
• Error Handling

Requirements

• Python 3.10+
• A Kubernetes cluster with the KubeRay operator installed
• A valid kubeconfig (or running inside the cluster)

Development

# Clone and install
git clone https://github.com/roulbac/krayne.git
cd krayne
uv sync

# Run tests
uv run pytest

# Run integration tests (sandbox is provisioned automatically by test fixtures)
uv run pytest -m integration

License

Apache 2.0