> For the complete documentation index, see [llms.txt](https://docs.cloud.olakrutrim.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cloud.olakrutrim.com/developer-tools/krutrimconnect.md).

# KrutrimConnect

Connect Codex and OpenCode to Krutrim Cloud models with secure sign-in, model selection and reversible configuration.

## Overview

KrutrimConnect connects Codex and OpenCode to Krutrim Cloud inference. It handles API-key sign-in, model selection and coding-tool configuration, and restores your saved configuration when you disconnect.

1. Install KrutrimConnect.
2. Sign in with your [API key](https://docs.cloud.olakrutrim.com/basics/key-management-system/model-api-keys.md).
3. Choose a model from the catalogue.
4. Connect Codex or OpenCode.

## Before you begin

You need a [Krutrim Cloud API key](https://docs.cloud.olakrutrim.com/basics/key-management-system/model-api-keys.md) and Codex or OpenCode installed separately. KrutrimConnect includes its own runtime; Node.js, npm and administrator access are not required.

[Download the latest release](https://github.com/ola-krutrim/krutrimconnect/releases/latest) · [Source and user guide](https://github.com/ola-krutrim/krutrimconnect)

## Installation

{% tabs %}
{% tab title="macOS and Linux" %}
Run this in your terminal:

```sh
(
  set -eu
  connect_installer="$(mktemp)"
  trap 'rm -f "$connect_installer"' EXIT
  curl --proto '=https' --proto-redir '=https' -fsSL \
    https://raw.githubusercontent.com/ola-krutrim/krutrimconnect/main/install.sh \
    -o "$connect_installer"
  sh "$connect_installer"
)
```

The installer downloads the latest stable release, verifies its checksum and installs KrutrimConnect for your user. Available archives cover macOS Apple Silicon, macOS Intel, Linux x64 with glibc and Alpine Linux x64 with musl. The installer selects the matching glibc or musl archive automatically.
{% endtab %}

{% tab title="Windows" %}
Run in PowerShell 5.1 or later:

```powershell
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/ola-krutrim/krutrimconnect/main/install.ps1" -OutFile "$env:TEMP\krutrimconnect-install.ps1"
powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$env:TEMP\krutrimconnect-install.ps1"
$env:Path = "$env:LOCALAPPDATA\KrutrimConnect\bin;$env:Path"
krutrimconnect --version
```

Windows x64 installs under `%LOCALAPPDATA%\KrutrimConnect` and uses Windows Credential Manager.
{% endtab %}
{% endtabs %}

<details>

<summary><strong>Advanced / troubleshooting install</strong></summary>

**Alpine prerequisites**

On Alpine, install the system libraries and download tools first:

```sh
apk add --no-cache ca-certificates curl libstdc++
```

**PATH**

If your shell cannot find the installed command:

```sh
export PATH="$HOME/.local/bin:$PATH"
krutrimconnect --version
```

Follow the installer's instructions to make the PATH change persistent.

On Windows, add the `bin` directory under `%LOCALAPPDATA%\KrutrimConnect` to your user PATH for future terminals, or set `$env:KRUTRIM_CONNECT_MODIFY_PATH = "1"` before running the installer to opt into a persistent PATH update.

**Linux keychain**

Linux keychain storage requires `secret-tool` and a running, unlocked Secret Service backend. See Credential storage below for headless Linux.

**Unsupported archives**

Windows ARM64/x86 and Alpine ARM64 archives are not available.

</details>

## Get started

{% stepper %}
{% step %}

### Sign in

[Create or manage your API key](https://docs.cloud.olakrutrim.com/basics/key-management-system/model-api-keys.md), then run:

```sh
krutrimconnect login
krutrimconnect auth status
```

Paste the API key at the masked prompt. Login validates the key without inference and stores it in your OS keychain.

{% hint style="danger" %}
Never pass API keys as command-line arguments.
{% endhint %}
{% endstep %}

{% step %}

### Choose a model

```sh
krutrimconnect models list
krutrimconnect models show MODEL_ID
```

Replace `MODEL_ID` with an exact model ID from the catalogue. Use `models list --refresh` for a fresh catalogue or `models list --offline` for the bundled snapshot. Listing does not perform inference. A listed model may not support every capability required by your coding tool.
{% endstep %}

{% step %}

### Connect your coding tool

{% tabs %}
{% tab title="Codex" %}

```sh
krutrimconnect codex on --model MODEL_ID
```

Restart Codex after connecting.
{% endtab %}

{% tab title="OpenCode" %}

```sh
krutrimconnect opencode on --model MODEL_ID
```

Launch OpenCode with `opencode` and use it normally.
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Activation checks the selected model's compatibility and may incur inference charges. It fails without changing configuration when required capabilities cannot be established.
{% endhint %}
{% endstep %}

{% step %}

### Disconnect when needed

Restore your saved tool configuration:

```sh
krutrimconnect codex off
krutrimconnect opencode off
```

{% endstep %}
{% endstepper %}

## Credential storage

The OS keychain is the default.

```sh
krutrimconnect login --allow-file-fallback
```

{% hint style="info" %}
On headless Linux without Secret Service, explicitly opt into a plaintext file with restricted permissions.
{% endhint %}

Windows requires Credential Manager and does not allow the plaintext fallback.

For automated input, `krutrimconnect login --from-env` reads `KRUTRIM_API_KEY`, or `krutrimconnect login --stdin` reads a key piped from your secret manager. Ordinary commands do not implicitly use an ambient environment key. Disconnect tools before replacing a stored key.

## Command reference

Every command starts with `krutrimconnect`. Use `krutrimconnect COMMAND --help` for options.

### Account and credentials

| Command               | Purpose                                                          |
| --------------------- | ---------------------------------------------------------------- |
| `login`               | Validate and store your API key.                                 |
| `auth status`         | Show local credential status without displaying the key.         |
| `logout --disconnect` | Restore connected tools and remove accessible local credentials. |

### Models

| Command                | Purpose                                                        |
| ---------------------- | -------------------------------------------------------------- |
| `models list`          | List catalogue models, with live lookup and snapshot fallback. |
| `models show MODEL_ID` | Show details from the bundled catalogue.                       |

Model listing supports query, publisher and modality filters. See command help for JSON output where supported.

### Coding tools

| Command                                            | Purpose                                                 |
| -------------------------------------------------- | ------------------------------------------------------- |
| `codex on --model MODEL_ID`                        | Connect Codex to the selected model.                    |
| `codex off`                                        | Restore the saved Codex configuration.                  |
| `status`                                           | Show the Codex connection state.                        |
| `opencode on --model MODEL_ID`                     | Connect OpenCode to the selected model.                 |
| `opencode off`                                     | Restore the saved OpenCode configuration.               |
| `opencode status`                                  | Show the OpenCode connection state.                     |
| `opencode run [args...]`                           | Launch OpenCode and forward arguments.                  |
| `chat --model MODEL_ID --accept-inference-charges` | Send a potentially billable prompt directly to Krutrim. |

{% hint style="warning" %}
`chat --model MODEL_ID --accept-inference-charges` sends a potentially billable prompt directly to Krutrim.
{% endhint %}

### Maintenance

| Command           | Purpose                                                                                     |
| ----------------- | ------------------------------------------------------------------------------------------- |
| `doctor`          | Check configuration, credentials, reachability and recorded capabilities without inference. |
| `upgrade --check` | Check for a newer stable release.                                                           |
| `upgrade`         | Download and install the latest stable release.                                             |
| `uninstall`       | Restore managed configurations, remove accessible credentials and remove the CLI.           |
| `--version`       | Print the installed version.                                                                |
| `--help`          | Show command help.                                                                          |

## Upgrade or remove

### Upgrade

```sh
krutrimconnect upgrade --check
krutrimconnect upgrade
```

Restart coding-tool sessions after upgrading, then reconnect tools to update their stored runtime references. Older runtimes are retained for existing sessions.

### Log out

To disconnect tools and remove local credentials while keeping the CLI:

```sh
krutrimconnect logout --disconnect
```

### Uninstall

To remove KrutrimConnect and its managed connections and credentials:

```sh
krutrimconnect uninstall
```

On Windows, close older KrutrimConnect sessions before uninstalling. Executable cleanup finishes after the uninstall command exits.

{% hint style="info" %}
Logout and uninstall do not revoke your [Cloud API key](https://docs.cloud.olakrutrim.com/basics/key-management-system/model-api-keys.md); revoke or rotate it in Krutrim Cloud when needed.
{% endhint %}

## Troubleshooting

```sh
krutrimconnect status
krutrimconnect opencode status
krutrimconnect doctor
krutrimconnect doctor --model MODEL_ID
```

* If activation fails, check the exact model ID, API-key validation and diagnostics. Model availability alone does not establish coding-tool compatibility.
* If configuration changed outside KrutrimConnect, review the reported changes before forcing restoration. Keep your backups and do not delete configuration or credential-helper paths to bypass ownership checks.

[Report an issue](https://github.com/ola-krutrim/krutrimconnect/issues) with redacted diagnostics. Follow the project's [security guidance](https://github.com/ola-krutrim/krutrimconnect/blob/main/SECURITY.md) for vulnerabilities.

## Terms and licence

KrutrimConnect source is licensed under [Apache 2.0](https://github.com/ola-krutrim/krutrimconnect/blob/main/LICENSE), with [third-party notices](https://github.com/ola-krutrim/krutrimconnect/blob/main/NOTICE). Krutrim Cloud use is governed by its [Terms & Conditions](https://www.olakrutrim.com/terms-and-conditions) and [Privacy Policy](https://www.olakrutrim.com/privacy-policy). Review and test AI-generated output before use.
