Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 45 additions & 1 deletion docs/free-tiers.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,58 @@ What free tiers do in practice, measured against real providers in October 2026.
| Provider | What we saw |
|---|---|
| OpenRouter | Free models are limited to 20 requests per minute, and 50 per day on a key with no credits. A one-time purchase of $10 or more in credits raises the daily limit to 1,000. A key limit of $0 still allows `:free` models. |
| OpenCode Zen | The free models answer `403 FreeTierError` ("the free tier can only be used from within OpenCode") for any other client. A router cannot use them with any key. |
| OpenCode Zen | The free models answer `403 FreeTierError` ("the free tier can only be used from within OpenCode") unless the request carries the shape the official OpenCode client sends. The router sends that shape, so these models are routable. See [OpenCode Zen request shape](#opencode-zen-request-shape). |
| Ollama Cloud | The free plan answers `402` for the premium models. |
| Cerebras | Answers `402` for models outside the free allowance. |
| Google AI | Free quotas are very small, or zero for some models. |
| Requesty | 200 requests per day. Most of its free models may train on prompts. |

Free models on several providers may train on the prompts you send. Do not route private code or data through them.

## OpenCode Zen request shape

OpenCode Zen's free models are not restricted by account or entitlement. They are restricted by
*request shape*: the endpoint only answers requests that look like they came from the official
OpenCode client. A request that does not is refused with `403 FreeTierError` and the message
"OpenCode's free tier can only be used from within OpenCode".

Four elements are required. Each one was verified individually against the live endpoint by
changing a single element at a time:

| Element | Required value |
|---|---|
| `User-Agent` | `opencode/<version>` (any version from 1.18.0 upwards) |
| `x-opencode-session` | `ses_` + 12 lowercase hex characters + 14 base62 characters = 30 characters in total |
| `stream` | `true` |
| `tools` | a function named exactly `read` |

A `You are opencode` system message is *not* required — the request is accepted without it.

Two details are easy to get wrong:

- The session id is validated by **shape**, not by value. The 12-character hex block is a 48-bit
millisecond timestamp, and only the format is checked. A 32-character hex id, or an id of 28, 29
or 31 characters, is refused.
- The `read` tool must be named exactly `read`. A differently named function does not satisfy the
gate.

The router applies this shape to OpenCode requests, so the free models are routable.

**No API key is required for the free models.** The key is not what makes them work — the request
shape is. Measured against the live endpoint:

| `Authorization` header | Result |
|---|---|
| absent | accepted |
| `Bearer public` | accepted |
| `Bearer ` (empty) | accepted |
| a key that is not a real OpenCode key | `500` "Invalid credential" |

A missing key is therefore harmless, but a *wrong* key is not: it fails with a server error
rather than being ignored. The router sends no `Authorization` header when no OpenCode key is
configured, which is the correct behavior for the free tier. A key is still required for the paid
Zen models.

## Model ids go stale

A free variant can disappear while its slug still lists elsewhere. For example, OpenRouter answers `404` ("this model is unavailable for free") for a `:free` slug that has become paid, and names the paid slug. A model list is not proof that the model is usable, so check with a real request.
Expand Down
90 changes: 86 additions & 4 deletions lib/server.js
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ import { capLength, isSafeObjectKey } from './text.js';
import { rateLimit } from 'express-rate-limit';
import { createAdminAuth, createAdminMiddleware, createAuthRoutes, parseAllowedHosts, parseAllowedOrigins } from './admin-guard.js';
import { classifyFailureStatus, createTelemetryStore, normalizeTelemetryStore, recordFailure, recordSuccess, reliabilityMultiplier, summarizeTelemetry, summarizeTelemetryEntry } from './telemetry.js';
import { createHash, randomUUID } from 'crypto';
import { createHash, randomInt, randomUUID } from 'crypto';
import { getAutostartStatus } from './autostart.js';
import { buildWindowsPostUpdateRestartCommand, fetchLatestNpmVersion, isRunningFromSource, isVersionNewer, runUpdateCommand } from './update.js';
import { DEFAULT_MODEL_QUALITY, MODEL_QUALITY_CACHE_MS, fetchOpenRouterQualityIndex, resolveModelQuality } from './model-quality.js';
Expand Down Expand Up @@ -967,10 +967,41 @@ function makeOpencodeHeaderId(prefix) {
return `${prefix}_${randomUUID().replace(/-/g, '')}`;
}

// The OpenCode Zen free tier validates the session id's *shape*, not its value:
// `ses_` + 12 lowercase hex characters + 14 base62 characters = 30 characters
// in total. A 32-hex uuid (makeOpencodeHeaderId) is rejected with a
// FreeTierError, as are 28, 29, 31 and 40 character ids.
//
// The hex block is a 48-bit millisecond timestamp, which is what the official
// client mints. The value is not validated, but a current timestamp keeps the
// id from going stale.
const OPENCODE_SESSION_HEX_LENGTH = 12;
const OPENCODE_SESSION_TAIL_LENGTH = 14;
const OPENCODE_SESSION_BASE62 = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';

function randomBase62(length) {
let out = '';
for (let i = 0; i < length; i++) {
out += OPENCODE_SESSION_BASE62[randomInt(OPENCODE_SESSION_BASE62.length)];
}
return out;
}

export function makeOpencodeSessionId(now = Date.now()) {
const hex = (BigInt(now) & ((1n << 48n) - 1n)).toString(16).padStart(OPENCODE_SESSION_HEX_LENGTH, '0');
return `ses_${hex}${randomBase62(OPENCODE_SESSION_TAIL_LENGTH)}`;
}

// The Zen endpoint rejects requests that do not look like they came from the
// official client. A missing User-Agent (or a non-OpenCode one) fails the
// free-tier gate with `FreeTierError: OpenCode's free tier can only be used
// from within OpenCode`.
const OPENCODE_USER_AGENT = 'opencode/1.19.3';

export function buildOpencodeHeaders(options = {}) {
return {
'x-opencode-project': buildOpencodeProjectId(options.projectSeed),
'x-opencode-session': options.sessionId || makeOpencodeHeaderId('ses'),
'x-opencode-session': options.sessionId || makeOpencodeSessionId(),
'x-opencode-request': options.requestId || makeOpencodeHeaderId('req'),
'x-opencode-client': options.client || OPENCODE_CLIENT_HEADER,
};
Expand All @@ -987,6 +1018,9 @@ export function buildProviderRequestHeaders(providerKey, options = {}) {

if (providerKey === OPENCODE_PROVIDER_KEY) {
Object.assign(headers, buildOpencodeHeaders(options));
// The free-tier gate checks the User-Agent: without an `opencode/<version>`
// value the request is refused with FreeTierError.
headers['User-Agent'] = options.userAgent || OPENCODE_USER_AGENT;
} else if (providerKey === KIRO_PROVIDER_KEY) {
headers.Accept = KIRO_STREAM_ACCEPT;
headers['X-Amz-Target'] = KIRO_STREAMING_TARGET;
Expand Down Expand Up @@ -1324,9 +1358,59 @@ export function buildProviderRequestBody(providerKey, body, modelId, options = {
if (providerKey === KIRO_PROVIDER_KEY) {
return buildKiroRequestPayload(body, modelId || body?.model, options);
}
if (providerKey === OPENCODE_PROVIDER_KEY) {
return buildOpencodeRequestPayload(body, options);
}
return body;
}

// The OpenCode Zen free tier accepts a request only if it carries the shape
// the official client sends. Two body-level conditions are required:
//
// * `stream: true` -- a non-streaming request is refused with FreeTierError.
// * a tool named exactly `read` -- a request without it is refused too.
//
// A `You are opencode` system message is *not* required, so it is only added
// when the caller did not supply a system message of its own.
const OPENCODE_READ_TOOL = {
type: 'function',
function: {
name: 'read',
description: 'Read a file from the local filesystem.',
parameters: {
type: 'object',
properties: {
filePath: { type: 'string', description: 'The path of the file to read.' },
offset: { type: 'number', description: 'Optional line offset to start reading from.' },
limit: { type: 'number', description: 'Optional maximum number of lines to read.' },
},
required: ['filePath'],
},
},
};

export function buildOpencodeRequestPayload(body, options = {}) {
const payload = { ...(body || {}) };
payload.stream = true;

const tools = Array.isArray(payload.tools) ? payload.tools : [];
const hasReadTool = tools.some((tool) => {
const name = tool?.function?.name ?? tool?.name;
return name === 'read';
});
if (!hasReadTool) {
payload.tools = [...tools, OPENCODE_READ_TOOL];
}

const messages = Array.isArray(payload.messages) ? payload.messages : [];
const hasSystemMessage = messages.some((message) => message?.role === 'system');
if (!hasSystemMessage && options.addSystemPrompt !== false) {
payload.messages = [{ role: 'system', content: 'You are opencode' }, ...messages];
}

return payload;
}

export function parseKiroEventFrame(data) {
try {
const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
Expand Down Expand Up @@ -4305,7 +4389,6 @@ export async function runServer(config, port, enableLog = true, bannedModels = [

let headers = buildProviderRequestHeaders(best.providerKey, {
apiKey: providerAuth.token,
sessionId: makeOpencodeHeaderId('ses'),
requestId: makeOpencodeHeaderId('req'),
});
const kiroOptions = best.providerKey === KIRO_PROVIDER_KEY
Expand All @@ -4328,7 +4411,6 @@ export async function runServer(config, port, enableLog = true, bannedModels = [
providerAuth = { token: fallbackToken, authSource: 'api-key', providerUrlOverride: providerAuth.providerUrlOverride };
headers = buildProviderRequestHeaders(best.providerKey, {
apiKey: fallbackToken,
sessionId: makeOpencodeHeaderId('ses'),
requestId: makeOpencodeHeaderId('req'),
});
providerPayload = buildProviderRequestBody(best.providerKey, payload, best.modelId, kiroOptions);
Expand Down
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@schaetzkc/modelrelay",
"version": "1.28.0",
"version": "1.28.1",
"description": "OpenAI-compatible local router that benchmarks free coding models across providers and forwards requests to the best available model.",
"keywords": [
"nvidia",
Expand Down
72 changes: 71 additions & 1 deletion test/test.js
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ import { getConfiguredTagNames, getModelTagKey, getModelTags as getUserModelTags
import { resolveAutostartExecPath, resolveAutostartNodePath } from '../lib/autostart.js'
import { normalizeSecret, buildOpenAICompatibleInstanceKey as buildInstanceKeyForSafetyTests, exportConfigToken, getApiKey, getApiKeyPool, getMaxTurns, getPinningMode, getProviderBaseUrl, getProviderModelId, getProviderPingIntervalMs, hasMultipleKeys, importConfigToken, normalizeConfigShape, isOpenAICompatibleInstanceKey, getBaseProviderKey, getOpenAICompatibleInstanceId, buildOpenAICompatibleInstanceKey, listOpenAICompatibleEndpoints, upsertOpenAICompatibleEndpoint, removeOpenAICompatibleEndpoint } from '../lib/config.js'
import { buildNpmInstallInvocation, buildWindowsPostUpdateRestartCommand, getForcedUpdateVersion, getLocalUpdateTarballPath, getLocalUpdateVersion, isRunningFromSource, shouldStopAutostartBeforeUpdate } from '../lib/update.js'
import { isKnownProviderKey, captureProxyRateLimit, buildKiroRequestPayload, buildKiroSocialLoginUrl, buildOpencodeHeaders, buildOpencodeProjectId, buildProviderRequestBody, buildProviderRequestHeaders, exchangeKiroSocialAuthFlow, exchangeKiroSocialCode, extractKiroEmailFromAccessToken, extractOllamaModelRecords, extractOpenAICompatibleModelRecords, buildOpenAICompatibleModelsListUrl, getAccountStatus, getKiroRefreshToken, hasKiroAuthConfigured, getPinnedModelCandidate, getPinnedModelMatches, isProviderAuthOptional, isProviderBearerAuthEnabled, parseKiroEventFrame, pollKiroBuilderIdToken, providerWantsBearerAuth, resolveKiroOAuthAccessToken, shouldRetryOptionalProviderWithBearer, startKiroBuilderIdDeviceAuth, startKiroSocialAuthFlow, toOllamaModelMeta, toOpenAICompatibleDiscoveredModelMeta, toOpenCodeModelMeta, toOpenRouterModelMeta, toKiloCodeModelMeta, transformKiroResponse } from '../lib/server.js'
import { isKnownProviderKey, captureProxyRateLimit, buildKiroRequestPayload, buildKiroSocialLoginUrl, buildOpencodeHeaders, buildOpencodeProjectId, buildOpencodeRequestPayload, makeOpencodeSessionId, buildProviderRequestBody, buildProviderRequestHeaders, exchangeKiroSocialAuthFlow, exchangeKiroSocialCode, extractKiroEmailFromAccessToken, extractOllamaModelRecords, extractOpenAICompatibleModelRecords, buildOpenAICompatibleModelsListUrl, getAccountStatus, getKiroRefreshToken, hasKiroAuthConfigured, getPinnedModelCandidate, getPinnedModelMatches, isProviderAuthOptional, isProviderBearerAuthEnabled, parseKiroEventFrame, pollKiroBuilderIdToken, providerWantsBearerAuth, resolveKiroOAuthAccessToken, shouldRetryOptionalProviderWithBearer, startKiroBuilderIdDeviceAuth, startKiroSocialAuthFlow, toOllamaModelMeta, toOpenAICompatibleDiscoveredModelMeta, toOpenCodeModelMeta, toOpenRouterModelMeta, toKiloCodeModelMeta, transformKiroResponse } from '../lib/server.js'
const __dirname = dirname(fileURLToPath(import.meta.url))
const ROOT = join(__dirname, '..')

Expand Down Expand Up @@ -811,6 +811,76 @@ describe('provider api key resolution', () => {
assert.equal(headers['x-opencode-client'], 'cli')
})

it('mints OpenCode session ids in the shape the Zen free tier requires', () => {
// `ses_` + 12 lowercase hex + 14 base62 = 30 characters in total.
for (let i = 0; i < 20; i++) {
const sessionId = makeOpencodeSessionId()
assert.match(sessionId, /^ses_[0-9a-f]{12}[0-9A-Za-z]{14}$/)
// `ses_` (4) + 12 hex + 14 base62 = 30 characters in total.
assert.equal(sessionId.length, 30)
assert.equal(sessionId.slice(4).length, 26)
}
})

it('derives the OpenCode session hex block from the current timestamp', () => {
const now = 1792530294000
const sessionId = makeOpencodeSessionId(now)
assert.ok(sessionId.startsWith('ses_'))
assert.equal(sessionId.slice(4, 16), (BigInt(now) & ((1n << 48n) - 1n)).toString(16).padStart(12, '0'))
})

it('sends a Zen-shaped session id when no explicit one is supplied', () => {
// The header path must not fall back to the 32-hex uuid form: that shape
// is refused with FreeTierError by the Zen free tier.
const headers = buildProviderRequestHeaders('opencode', {})
assert.match(headers['x-opencode-session'], /^ses_[0-9a-f]{12}[0-9A-Za-z]{14}$/)
assert.equal(headers['x-opencode-session'].length, 30)
})

it('sends an OpenCode User-Agent so the Zen free tier accepts the request', () => {
const headers = buildProviderRequestHeaders('opencode', {
projectSeed: 'C:/example/project',
sessionId: 'ses_test',
requestId: 'req_test',
})

assert.match(headers['User-Agent'], /^opencode\/\d+\.\d+\.\d+$/)
})

it('adds the OpenCode free-tier body shape: stream, a read tool and the system prompt', () => {
const payload = buildOpencodeRequestPayload({
model: 'nemotron-3.5-super-vl-free',
messages: [{ role: 'user', content: 'Hello' }],
})

assert.equal(payload.stream, true)
assert.ok(payload.tools.some((tool) => tool.function.name === 'read'))
assert.equal(payload.messages[0].role, 'system')
assert.equal(payload.messages[0].content, 'You are opencode')
})

it('keeps a caller-supplied read tool and system message when rewriting the OpenCode body', () => {
const payload = buildOpencodeRequestPayload({
model: 'nemotron-3.5-super-vl-free',
messages: [{ role: 'system', content: 'You are opencode' }, { role: 'user', content: 'Hello' }],
tools: [{ type: 'function', function: { name: 'read', parameters: { type: 'object' } } }],
})

assert.equal(payload.tools.length, 1)
assert.equal(payload.messages.length, 2)
assert.equal(payload.messages[0].content, 'You are opencode')
})

it('routes the OpenCode provider request body through the free-tier shape', () => {
const payload = buildProviderRequestBody('opencode', {
model: 'nemotron-3.5-super-vl-free',
messages: [{ role: 'user', content: 'Hello' }],
}, 'nemotron-3.5-super-vl-free')

assert.equal(payload.stream, true)
assert.ok(payload.tools.some((tool) => tool.function.name === 'read'))
})

it('adds Kiro SDK headers to provider requests', () => {
const headers = buildProviderRequestHeaders('kiro', {
apiKey: 'kiro-key',
Expand Down