How to create a ClearRun client (createKernelClient)

Call createKernelClient(). It finds your key in hosted.apiKey, then CLEARRUN_API_KEY, then the file saved by clearrun login. Creating the client never throws for a missing key. With no key and no mock option, the first score, evaluate or chat call rejects with MissingApiKeyError. verify and mock mode need no key.

Last updated November 9, 2026

Applies to version 1.2.0 of @clearrun/sdk and @clearrun/cli.

Steps

With a key from the environment

import { createKernelClient } from '@clearrun/sdk';

// reads CLEARRUN_API_KEY
const client = createKernelClient();

With an explicit key and options

const client = createKernelClient({
  hosted: {
    apiKey: process.env.CLEARRUN_API_KEY,
    timeoutMs: 15000,
  },
});

For tests, in mock mode

const client = createKernelClient({ forceMock: true });

Options

Options
Option	What it does
`hosted.apiKey`	Your key. Sent as `Authorization: Bearer`
`hosted.baseUrl`	Default `https://api.clearrun.net`
`hosted.timeoutMs`	Abort a request after this many milliseconds
`forceMock`	Use mock mode. No network, no key
`mock.chatResponse`	Mock chat reply. Passing `mock` also turns on mock mode
`deps.fetch`	Your own `fetch`
`env`	Where to read `CLEARRUN_API_KEY` and the config path. Default `process.env`

Methods

score, evaluate, chat and verify. The first three need a key and use credits. verify does not.

It never falls back to mock

If no key is found and you didn't ask for mock mode, the first score, evaluate or chat call rejects with MissingApiKeyError. It won't hand you local test scores by surprise.