Mock mode or hosted scores: which should I use?

Use mock mode to build and test your code without an account. Use hosted scores when you need real scores. Mock scores are local test values, never signed, with no receipt.

Last updated

Steps

  1. Start in mock mode

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

const client = createKernelClient({ forceMock: true });
const { verdict } = await client.score({ responseText: 'Our API never stores customer data.' });
console.log(verdict.score, verdict.summary);

  2. Switch to hosted

    Remove forceMock and set CLEARRUN_API_KEY. A verified free account can create one developer key.

Mock mode

Good for building before you have a key, unit tests, and checking your code handles every verdict field. Hosted scores work differently: a later run of the same text can score differently.

Not for any decision about a real answer. The mock score depends only on the text length.

The CLI and MCP server do not have a mock mode.

Hosted scores

From api.clearrun.net. They need an API key and use credits. Each successful call is signed and returns a receipt you can look up later, with no key. That does not mean the answer is true.

No silent fallback

If you don't pass forceMock and no key is set, the SDK throws MissingApiKeyError. It never falls back to a mock score on its own.