Install and Configure the Client

This section explains how to install runapy, select the right client type for your environment and configure authentication.

Prerequisites

• NVIDIA Run:ai control plane version ≥ 2.18 - Required for compatibility
• Python version ≥ 3.8 - Required for dependency compatibility
• NVIDIA Run:ai access keys - Required to generate the client_id and client_secret credentials:
  • To create organization-level service accounts, see Service accounts
  • To create user-level access keys, see User access keys

Installation

• For the latest NVIDIA Run:ai control plane:

pip install runapy

• For self-hosted environments, specify the minor version matching your control plane version. For example, with NVIDIA Run:ai 2.19 control plane:

pip install runapy~=1.219.0

To understand the versioning scheme, refer to the Versioning section.

Client Types

The Python client provides multiple client types tailored to different environments:

1. ApiClient - Standard synchronous client for sequential operations
2. ThreadedApiClient - Thread-safe client for parallel operations in multithreaded environments
3. AsyncApiClient - Asynchronous client for async/await support

For additional configuration options, see Client configuration options.

Standard API Client

The below shows a basic example using the standard client:

from runai.configuration import Configuration
from runai.api_client import ApiClient
from runai.runai_client import RunaiClient
config = Configuration(
    client_id="your-client-id",
    client_secret="your-client-secret",
    runai_base_url="https://your-org.run.ai",
)
client = RunaiClient(ApiClient(config))
# Start making API calls
projects = client.organizations.projects.get_projects()

Multithreaded Operations

For parallel operations in a multithreaded environment, use ThreadedApiClient:

from runai.api_client import ThreadedApiClient
with RunaiClient(ThreadedApiClient(config)) as client:
    # These operations can run concurrently
    projects = client.organizations.projects.get_projects()

Asynchronous Operations

For async/await support, use AsyncApiClient:

import asyncio
from runai.api_client import AsyncApiClient
async def main():
    async with RunaiClient(AsyncApiClient(config)) as client:
        projects = await client.organizations.projects.get_projects()
asyncio.run(main())

Authentication Methods

The client supports three authentication methods:

Client Credentials

Use the client_id and client_secret from your NVIDIA Run:ai service accounts or user access keys:

config = Configuration(
    client_id="your-client-id",
    client_secret="your-client-secret",
    runai_base_url="https://your-org.run.ai"
)

Bearer Token

Direct authentication using a bearer token:

config = Configuration(
    bearer_token="your-bearer-token",
    runai_base_url="https://your-org.run.ai"
)

CLI v2 Token (Bearer Token)

The CLI v2 token method is useful for:

• Local development and testing
• Scripts running on machines with existing CLI authentication
• Maintaining consistent authentication with CLI sessions
• End user operations

Requirements:

• NVIDIA Run:ai CLI v2 is installed
• Successful runai login completed
• Valid authentication token in CLI config

from runai.cliv2_config_loader import CLIv2Config
# Default config path is ~/.runai
config = CLIv2Config()
# Or specify a custom path
config = CLIv2Config(cliv2_config_path="/path/to/.runai")
token = config.token
runai_base_url = config.control_plane_url
cluster_id = config.cluster_uuid
client = RunaiClient(
    cluster_id=cluster_id,
    bearer_token=token,
    runai_base_url=runai_base_url
)

Client Configuration Options