Skip to content

7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.

TypeScript

feat(cli): freellmapi doctor — prove a client's requests reach this gateway (#862)

OhOkThisIsFine1129fc4a214b
diff --git a/cli/package.json b/cli/package.json
index 17afcb58..a8ae7a2b 100644
--- a/cli/package.json
+++ b/cli/package.json
@@ -38,6 +38,8 @@
"dist/index.d.ts",
"dist/config-files.js",
"dist/config-files.d.ts",
+ "dist/doctor.js",
+ "dist/doctor.d.ts",
"dist/models.js",
"dist/models.d.ts",
"dist/tools.js",
diff --git a/cli/src/doctor.test.ts b/cli/src/doctor.test.ts
new file mode 100644
index 00000000..278d95fb
--- /dev/null
+++ b/cli/src/doctor.test.ts
@@ -0,0 +1,393 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+ DEFAULT_PROBE_TIMEOUT_MS,
+ claudeLayers,
+ codexLayers,
+ diagnose,
+ exitCodeFor,
+ managedSettingsDir,
+ managedSettingsPaths,
+ normalizeUrl,
+ probeGateway,
+ sameGateway,
+} from './doctor.js';
+
+const temporary: string[] = [];
+function tempHome(): string {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'freellmapi-doctor-'));
+ temporary.push(dir);
+ return dir;
+}
+afterEach(() => {
+ for (const dir of temporary.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+/** A fetch double that answers /livez exactly as the real gateway does. */
+function gatewayFetch(
+ body: unknown = { status: 'ok', version: '0.7.0', uptime_s: 12 },
+ status = 200,
+): typeof fetch {
+ return (async () => ({ status, json: async () => body })) as unknown as typeof fetch;
+}
+
+/** The real 503 body from routes/status.ts when the db or encryption key is down. */
+const UNAVAILABLE = { status: 'unavailable', version: '0.7.0', uptime_s: 12, checks: { db: false } };
+const deadFetch = (async () => { throw new Error('ECONNREFUSED'); }) as unknown as typeof fetch;
+
+function writeClaudeSettings(home: string, value: Record<string, unknown>): void {
+ const dir = path.join(home, '.claude');
+ fs.mkdirSync(dir, { recursive: true });
+ fs.writeFileSync(path.join(dir, 'settings.json'), JSON.stringify(value));
+}
+
+function writeCodexConfig(home: string, toml: string): void {
+ const dir = path.join(home, '.codex');
+ fs.mkdirSync(dir, { recursive: true });
+ fs.writeFileSync(path.join(dir, 'config.toml'), toml);
+}
+
+describe('managed settings locations', () => {
+ it('uses the documented system directory for each platform', () => {
+ expect(managedSettingsDir('darwin')).toBe('/Library/Application Support/ClaudeCode');
+ expect(managedSettingsDir('linux')).toBe('/etc/claude-code');
+ expect(managedSettingsDir('win32')).toBe('C:\\Program Files\\ClaudeCode');
+ });
+
+ it('falls back to the base file alone when there is no drop-in directory', () => {
+ // The usual case: an unreadable or absent managed-settings.d contributes
+ // nothing rather than failing the whole report.
+ const dir = tempHome();
+ expect(managedSettingsPaths('linux', dir)).toEqual([path.join(dir, 'managed-settings.json')]);
+ });
+
+ it('ranks managed-settings.d drop-ins above the base file, last one first', () => {
+ // The drop-in files are merged alphabetically ON TOP of the base, so the
+ // alphabetically LAST one wins and the base loses to all of them. Getting
+ // this order backwards would name the wrong layer as effective for a
+ // fleet-managed install — the exact confident-wrong answer doctor exists
+ // to prevent.
+ const dir = tempHome();
+ fs.mkdirSync(path.join(dir, 'managed-settings.d'));
+ for (const name of ['20-b.json', '10-a.json', 'notes.txt']) {
+ fs.writeFileSync(path.join(dir, 'managed-settings.d', name), '{}');
+ }
+
+ expect(managedSettingsPaths('linux', dir)).toEqual([
+ path.join(dir, 'managed-settings.d', '20-b.json'),
+ path.join(dir, 'managed-settings.d', '10-a.json'),
+ path.join(dir, 'managed-settings.json'),
+ ]);
+ });
+});
+
+describe('url comparison', () => {
+ it('ignores trailing slashes, a /v1 suffix, and host case', () => {
+ expect(normalizeUrl('http://Localhost:3000/v1/')).toBe('http://localhost:3000');
+ expect(sameGateway('http://localhost:3000', 'http://localhost:3000/v1')).toBe(true);
+ expect(sameGateway('http://localhost:3000', 'http://localhost:3001')).toBe(false);
+ expect(sameGateway(undefined, 'http://localhost:3000')).toBe(false);
+ });
+
+ it('keeps a path prefix, so two mounts on one host are not confused', () => {
+ // A gateway mounted under a prefix is a different endpoint. Folding the
+ // path away reported these as the same gateway.
+ expect(normalizeUrl('http://host/gateway/v1/')).toBe('http://host/gateway');
+ expect(sameGateway('http://host/gateway', 'http://host/other')).toBe(false);
+ expect(sameGateway('http://host/gateway/v1', 'http://host/gateway/')).toBe(true);
+ expect(sameGateway('http://host/gateway', 'http://host')).toBe(false);
+ });
+
+ it('keeps path case, which is case-sensitive, while folding the host', () => {
+ expect(normalizeUrl('HTTP://Host:3000/Gateway')).toBe('http://host:3000/Gateway');
+ expect(sameGateway('http://host/Gateway', 'http://host/gateway')).toBe(false);
+ });
+
+ it('drops query and fragment, which never identify the endpoint', () => {
+ expect(normalizeUrl('http://host:3000/v1?k=1#x')).toBe('http://host:3000');
+ });
+
+ it('falls back to lexical trimming for an unparseable value', () => {
+ // A malformed config value must still produce a report, not an exception.
+ expect(normalizeUrl('localhost:3000/v1/')).toBe('localhost:3000');
+ });
+});
+
+describe('claude precedence', () => {
+ it('ranks a settings env block ABOVE the inherited shell environment', () => {
+ // The easy thing to get backwards, and I did: Claude Code writes each
+ // `env` entry into the process environment at startup, REPLACING what the
+ // shell exported. The shell is the lowest layer, not the highest.
+ const home = tempHome();
+ writeClaudeSettings(home, { env: { ANTHROPIC_BASE_URL: 'http://localhost:3000' } });
+ const layers = claudeLayers({ ANTHROPIC_BASE_URL: 'https://api.anthropic.com' }, home, tempHome());
+
+ expect(layers[0]).toMatchObject({ value: 'http://localhost:3000', effective: true });
+ expect(layers[1]).toMatchObject({ value: 'https://api.anthropic.com', effective: false });
+ });
+
+ it('uses the shell value when no settings file names one', () => {
+ expect(claudeLayers({ ANTHROPIC_BASE_URL: 'http://localhost:3000' }, tempHome(), tempHome())[0])
+ .toMatchObject({ value: 'http://localhost:3000', effective: true });
+ });
+
+ it('ranks project-local settings above the user scope', () => {
+ const home = tempHome();
+ const project = tempHome();
+ writeClaudeSettings(home, { env: { ANTHROPIC_BASE_URL: 'http://user:1' } });
+ fs.mkdirSync(path.join(project, '.claude'), { recursive: true });
+ fs.writeFileSync(
+ path.join(project, '.claude', 'settings.local.json'),
+ JSON.stringify({ env: { ANTHROPIC_BASE_URL: 'http://project-local:2' } }),
+ );
+
+ expect(claudeLayers({}, home, project)[0])
+ .toMatchObject({ value: 'http://project-local:2', effective: true });
+ });
+
+ it('honours CLAUDE_CONFIG_DIR for the user scope', () => {
+ // Relocates the user scope wholesale; missing it reads a settings file the
+ // running tool never opens.
+ const home = tempHome();
+ const configDir = tempHome();
+ writeClaudeSettings(home, { env: { ANTHROPIC_BASE_URL: 'http://ignored:1' } });
+ fs.writeFileSync(
+ path.join(configDir, 'settings.json'),
+ JSON.stringify({ env: { ANTHROPIC_BASE_URL: 'http://relocated:2' } }),
+ );
+
+ expect(claudeLayers({ CLAUDE_CONFIG_DIR: configDir }, home, tempHome())[0]?.value)
+ .toBe('http://relocated:2');
+ });
+
+ it('reports no layers rather than throwing on absent or malformed settings', () => {
+ const home = tempHome();
+ expect(claudeLayers({}, home, tempHome())).toEqual([]);
+ fs.mkdirSync(path.join(home, '.claude'), { recursive: true });
+ fs.writeFileSync(path.join(home, '.claude', 'settings.json'), '{ not json');
+ expect(claudeLayers({}, home, tempHome())).toEqual([]);
+ });
+});
+
+describe('codex precedence', () => {
+ it('resolves the SELECTED provider, not the first base_url in the file', () => {
+ // Codex names a provider and the provider carries the url. Reading any
+ // base_url would report a provider the user is not selecting.
+ const home = tempHome();
+ writeCodexConfig(home, [
+ 'model_provider = "freellmapi"',
+ '',
+ '[model_providers.other]',
+ 'base_url = "http://not-this-one:9999/v1"',
+ '',
+ '[model_providers.freellmapi]',
+ 'base_url = "http://localhost:3000/v1"',
+ ].join('\n'));
+
+ expect(codexLayers({}, home)[0]).toMatchObject({
+ value: 'http://localhost:3000/v1',
+ effective: true,
+ });
+ });
+
+ it('reads the dotted-key spelling too', () => {
+ const home = tempHome();
+ writeCodexConfig(home, [
+ 'model_provider = "freellmapi"',
+ 'model_providers.freellmapi.base_url = "http://localhost:3000/v1"',
+ ].join('\n'));
+ expect(codexLayers({}, home)[0]?.value).toBe('http://localhost:3000/v1');
+ });
+
+ it('honours CODEX_HOME over the default location', () => {
+ const home = tempHome();
+ const alternate = tempHome();
+ writeCodexConfig(home, 'model_provider = "a"\n[model_providers.a]\nbase_url = "http://default:1/v1"');
+ writeCodexConfig(alternate, 'model_provider = "b"\n[model_providers.b]\nbase_url = "http://override:2/v1"');
+
+ const layers = codexLayers({ CODEX_HOME: path.join(alternate, '.codex') }, home);
+ expect(layers[0]?.value).toBe('http://override:2/v1');
+ });
+
+ it('records a selected provider that names no base_url instead of skipping it', () => {
+ const home = tempHome();
+ writeCodexConfig(home, 'model_provider = "freellmapi"\n');
+ const layer = codexLayers({}, home)[0];
+ expect(layer.effective).toBe(true);
+ expect(layer.value).toBeUndefined();
+ expect(layer.source).toContain('no base_url found');
+ });
+});
+
+describe('verdicts', () => {
+ const url = 'http://localhost:3000';
+
+ it('routed only when the tool reaches THIS gateway', async () => {
+ const report = await diagnose('claude', {
+ expectedUrl: url,
+ env: { ANTHROPIC_BASE_URL: url },
+ homeDir: tempHome(), cwd: tempHome(),
+ fetchImpl: gatewayFetch(),
+ });
+ expect(report.verdict).toBe('routed');
+ expect(report.gateway?.version).toBe('0.7.0');
+ });
+
+ it('elsewhere — not routed — when the tool reaches a different host that is alive', async () => {
+ // The regression this guards: reporting `routed` for a Claude Code pinned
+ // to api.anthropic.com, because it does reach what it is configured to
+ // reach. That is a confident wrong answer to the question being asked.
+ const report = await diagnose('claude', {
+ expectedUrl: url,
+ env: { ANTHROPIC_BASE_URL: 'https://api.anthropic.com' },
+ homeDir: tempHome(), cwd: tempHome(),
+ fetchImpl: gatewayFetch(),
+ });
+ expect(report.verdict).toBe('elsewhere');
+ expect(report.detail).toContain('does not touch this gateway');
+ });
+
+ it('elsewhere when the right port answers, but not the way this gateway does', async () => {
+ const report = await diagnose('claude', {
+ expectedUrl: url,
+ env: { ANTHROPIC_BASE_URL: url },
+ homeDir: tempHome(), cwd: tempHome(),
+ fetchImpl: gatewayFetch({ hello: 'some other service' }),
+ });
+ expect(report.verdict).toBe('elsewhere');
+ });
+
+ it('shadowed names the layer that wins, and the value it beat', async () => {
+ const home = tempHome();
+ writeClaudeSettings(home, { env: { ANTHROPIC_BASE_URL: url } });
+ const report = await diagnose('claude', {
+ expectedUrl: url,
+ env: { ANTHROPIC_BASE_URL: 'https://api.anthropic.com' },
+ homeDir: home, cwd: tempHome(),
+ fetchImpl: gatewayFetch(),
+ });
+
+ expect(report.verdict).toBe('shadowed');
+ // The settings block is what wins, so it is what shadows — and the shell
+ // export the user probably set by hand is what got overridden.
+ expect(report.shadowedBy).toContain('settings.json');
+ expect(report.detail).toContain('process environment');
+ expect(report.detail).toContain('https://api.anthropic.com');
+ });
+
+ it('degraded — not routed, not elsewhere — when this gateway says it cannot serve', async () => {
+ // Routing is correct and the gateway is unmistakably this one; it is sick.
+ // `routed` would send the user hunting through config that is already
+ // right, and `elsewhere` would blame a service that is not there.
+ const report = await diagnose('claude', {
+ expectedUrl: url,
+ env: { ANTHROPIC_BASE_URL: url },
+ homeDir: tempHome(), cwd: tempHome(),
+ fetchImpl: gatewayFetch(UNAVAILABLE, 503),
+ });
+ expect(report.verdict).toBe('degraded');
+ expect(report.detail).toContain('that IS this gateway');
+ expect(report.detail).toContain('unavailable');
+ expect(report.gateway).toMatchObject({ identified: true, healthy: false });
+ });
+
+ it('unreachable when the configured endpoint answers nothing', async () => {
+ const report = await diagnose('claude', {
+ expectedUrl: url,
+ env: { ANTHROPIC_BASE_URL: url },
+ homeDir: tempHome(), cwd: tempHome(),
+ fetchImpl: deadFetch,
+ });
+ expect(report.verdict).toBe('unreachable');
+ expect(report.detail).toContain('ECONNREFUSED');
+ });
+
+ it('unknown when nothing configures the tool at all', async () => {
+ const report = await diagnose('claude', {
+ expectedUrl: url,
+ env: {},
+ homeDir: tempHome(), cwd: tempHome(),
+ fetchImpl: gatewayFetch(),
+ });
+ expect(report.verdict).toBe('unknown');
+ expect(report.detail).toContain('vendor default');
+ });
+
+ it('unknown, not a crash, for a tool doctor does not model', async () => {
+ const report = await diagnose('aider', { expectedUrl: url, env: {}, homeDir: tempHome() });
+ expect(report.verdict).toBe('unknown');
+ expect(report.detail).toContain('claude');
+ });
+});
+
+describe('probeGateway', () => {
+ it('requires all three /livez fields before claiming identity', async () => {
+ // /livez carries no product marker, so the shape is the only evidence
+ // available. Two of three fields is not it.
+ expect((await probeGateway('http://x', gatewayFetch({ status: 'ok', version: '1' }))).identified)
+ .toBe(false);
+ expect((await probeGateway('http://x', gatewayFetch())).identified).toBe(true);
+ });
+
+ it('treats a non-JSON body as reachable but unidentified', async () => {
+ const htmlFetch = (async () => ({
+ status: 200,
+ json: async () => { throw new Error('not json'); },
+ })) as unknown as typeof fetch;
+ expect(await probeGateway('http://x', htmlFetch))
+ .toMatchObject({ reachable: true, identified: false, healthy: false });
+ });
+
+ it('still IDENTIFIES the gateway when it answers 503 unavailable', async () => {
+ // The server really emits this when the db or encryption key is down, and
+ // it is unmistakably this gateway. Folding health into identity would
+ // report a correctly-routed sick gateway as a foreign service.
+ expect(await probeGateway('http://x', gatewayFetch(UNAVAILABLE, 503))).toMatchObject({
+ reachable: true,
+ identified: true,
+ healthy: false,
+ serviceStatus: 'unavailable',
+ status: 503,
+ });
+ });
+
+ it('treats an unrecognized status value as unhealthy, not unidentified', async () => {
+ // A status added later must degrade into a truthful "this gateway says
+ // <status>", never into a claim that it is some other service.
+ const probe = await probeGateway(
+ 'http://x',
+ gatewayFetch({ status: 'draining', version: '9', uptime_s: 1 }),
+ );
+ expect(probe).toMatchObject({ identified: true, healthy: false, serviceStatus: 'draining' });
+ });
+
+ it('is unhealthy when a non-2xx carries an ok body', async () => {
+ expect((await probeGateway('http://x', gatewayFetch(undefined, 500))).healthy).toBe(false);
+ });
+
+ it('honours the caller-supplied timeout instead of the hard-coded default', async () => {
+ // Threaded so a slow link is not misreported as unreachable. That the
+ // caller's 20ms fires at all is the proof: the 5s default would not have.
+ const neverAnswers = (async (_url: string, init: RequestInit) => new Promise((_resolve, reject) => {
+ init.signal?.addEventListener('abort', () => reject(new Error('The operation was aborted')));
+ })) as unknown as typeof fetch;
+
+ const started = Date.now();
+ const probe = await probeGateway('http://x', neverAnswers, 20);
+ expect(Date.now() - started).toBeLessThan(DEFAULT_PROBE_TIMEOUT_MS);
+ expect(probe).toMatchObject({ reachable: false, identified: false, healthy: false });
+ expect(probe.error).toContain('abort');
+ });
+});
+
+describe('exit code', () => {
+ it('is zero only when every tool is routed', () => {
+ expect(exitCodeFor([{ verdict: 'routed' } as never])).toBe(0);
+ expect(exitCodeFor([{ verdict: 'routed' } as never, { verdict: 'elsewhere' } as never])).toBe(1);
+ expect(exitCodeFor([{ verdict: 'unknown' } as never])).toBe(1);
+ // A gateway that cannot serve is a failed precondition, not a pass.
+ expect(exitCodeFor([{ verdict: 'degraded' } as never])).toBe(1);
+ });
+});
diff --git a/cli/src/doctor.ts b/cli/src/doctor.ts
new file mode 100644
index 00000000..e19b1e3f
--- /dev/null
+++ b/cli/src/doctor.ts
@@ -0,0 +1,508 @@
+// `freellmapi doctor` — does this tool's traffic actually reach this gateway?
+//
+// The load-bearing constraint: the verdict must be computed in a process that
+// INHERITS THE USER'S SESSION ENVIRONMENT. The server cannot answer this
+// question, because the failure being diagnosed is a request that never
+// arrives — there is nothing in any server-side log to look at. So the check
+// resolves each tool's effective connection the way that tool resolves it, in
+// this process, and only then asks the gateway whether it is alive.
+//
+// The motivating failure is real and silent: a launcher that sets
+// ANTHROPIC_BASE_URL into the process environment overrides the `env` block of
+// ~/.claude/settings.json, so a user who edited settings.json is routed
+// somewhere else entirely and nothing says so.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+// 'elsewhere' is not decoration. Without it the first real run of this command
+// reported `OK claude: routed` for a Claude Code pinned to api.anthropic.com —
+// technically "it reaches what it is configured to reach", and precisely the
+// confident-wrong answer the command exists to prevent. `routed` now means
+// "reaches THIS gateway", which is the only question the user is asking.
+export type Verdict = 'routed' | 'degraded' | 'elsewhere' | 'shadowed' | 'unreachable' | 'unknown';
+
+export interface Layer {
+ /** Where the value came from, in the tool's own vocabulary. */
+ source: string;
+ value?: string;
+ /** True for the layer whose value the tool will actually use. */
+ effective: boolean;
+}
+
+export interface ToolReport {
+ tool: string;
+ verdict: Verdict;
+ /** Every layer that set a value, highest precedence first. */
+ layers: Layer[];
+ /** The base URL the tool will really use, if one could be determined. */
+ effectiveUrl?: string;
+ /** For 'shadowed': the layer that beat the one the user probably edited. */
+ shadowedBy?: string;
+ /** Gateway identity, when the effective URL was probed. */
+ gateway?: GatewayProbe;
+ detail: string;
+}
+
+export interface GatewayProbe {
+ reachable: boolean;
+ /** Whether the response looks like this product. See probeGateway. */
+ identified: boolean;
+ /** Whether the gateway says it can actually serve requests right now. */
+ healthy: boolean;
+ /** The `status` field verbatim: 'ok', 'unavailable', or anything added later. */
+ serviceStatus?: string;
+ version?: string;
+ /** HTTP status of the /livez response. */
+ status?: number;
+ error?: string;
+}
+
+/**
+ * Normalize for comparison: scheme + host + port + path prefix, with any
+ * trailing slash and `/v1` suffix removed.
+ *
+ * The path is KEPT, and kept case-sensitively. A gateway mounted under a prefix
+ * (`http://host/gateway`) is a different endpoint from `http://host/other`, and
+ * folding the path away would report the two as the same gateway. Only the
+ * scheme and host are case-folded, because only those are case-insensitive.
+ * Query and fragment are dropped: they never identify the endpoint.
+ *
+ * The result is also what the probe is built on, so it must stay a usable URL.
+ */
+export function normalizeUrl(url: string): string {
+ const trimmed = url.trim();
+ const lexical = (): string => trimmed.replace(/\/+$/, '').replace(/\/v1$/i, '').toLowerCase();
+ let parsed: URL;
+ try {
+ parsed = new URL(trimmed);
+ } catch {
+ // Not parseable at all — fall back to lexical trimming rather than
+ // throwing, so a malformed config value still yields a report.
+ return lexical();
+ }
+ // A scheme-less value like `localhost:3000/v1` PARSES, as the opaque path
+ // `3000/v1` under a `localhost:` scheme, and rebuilding it from parts would
+ // produce nonsense. An empty host is the tell.
+ if (!parsed.host) return lexical();
+ const prefix = parsed.pathname.replace(/\/+$/, '').replace(/\/v1$/i, '');
+ return `${parsed.protocol.toLowerCase()}//${parsed.host.toLowerCase()}${prefix}`;
+}
+
+export function sameGateway(a: string | undefined, b: string | undefined): boolean {
+ if (!a || !b) return false;
+ return normalizeUrl(a) === normalizeUrl(b);
+}
+
+function readJsonIfPresent(file: string): Record<string, unknown> | undefined {
+ try {
+ if (!fs.existsSync(file)) return undefined;
+ // Claude Code's settings.json is strict JSON, not JSONC.
+ return JSON.parse(fs.readFileSync(file, 'utf8')) as Record<string, unknown>;
+ } catch {
+ return undefined;
+ }
+}
+
+/** The system directory holding Claude Code's MANAGED settings — the scope
+ * nothing else can override. */
+export function managedSettingsDir(platform: string = process.platform): string {
+ if (platform === 'win32') return 'C:\\Program Files\\ClaudeCode';
+ if (platform === 'darwin') return '/Library/Application Support/ClaudeCode';
+ return '/etc/claude-code';
+}
+
+/**
+ * Managed settings files, HIGHEST PRECEDENCE FIRST.
+ *
+ * Not one file. The same directory also supports a `managed-settings.d/`
+ * drop-in, whose `*.json` files are merged alphabetically ON TOP of the base
+ * `managed-settings.json` — so a drop-in outranks the base, and the
+ * alphabetically LAST drop-in outranks the ones before it. Reading only the
+ * base file is how this command would confidently name the wrong effective
+ * URL for exactly the fleet-managed install most likely to have one imposed:
+ * it would report the layer the operator can see and miss the one actually
+ * winning.
+ *
+ * An unreadable directory (the usual case — it does not exist) contributes
+ * nothing rather than failing the report.
+ */
+export function managedSettingsPaths(
+ platform: string = process.platform,
+ dir: string = managedSettingsDir(platform),
+): string[] {
+ const separator = platform === 'win32' ? '\\' : '/';
+ const dropInDir = `${dir}${separator}managed-settings.d`;
+ let dropIns: string[] = [];
+ try {
+ dropIns = fs.readdirSync(dropInDir)
+ .filter(name => name.endsWith('.json'))
+ .sort()
+ .reverse() // alphabetically last is merged last, so it wins
+ .map(name => `${dropInDir}${separator}${name}`);
+ } catch {
+ dropIns = [];
+ }
+ return [...dropIns, `${dir}${separator}managed-settings.json`];
+}
+
+/** ANTHROPIC_BASE_URL out of a settings file's `env` block. */
+function envBlockUrl(file: string): string | undefined {
+ const block = readJsonIfPresent(file)?.env;
+ if (!block || typeof block !== 'object' || Array.isArray(block)) return undefined;
+ const value = (block as Record<string, unknown>).ANTHROPIC_BASE_URL;
+ return typeof value === 'string' && value ? value : undefined;
+}
+
+/**
+ * Claude Code's base-URL layers, HIGHEST PRECEDENCE FIRST.
+ *
+ * The ordering that matters, and the one it is easy to get backwards: a
+ * settings file's `env` block BEATS the inherited shell environment. Claude
+ * Code writes each `env` entry into the process environment at startup and
+ * again when the file changes, replacing what the shell exported. So the
+ * process environment is the LOWEST layer here, not the highest.
+ *
+ * The familiar "my launcher overrode my settings.json" case is not a
+ * counter-example: a launcher that wins is writing MANAGED settings, which
+ * outrank every other scope — note that the rest of that same `env` block
+ * still applies, which is what makes the override so hard to see by reading
+ * config alone.
+ */
+export function claudeLayers(
+ env: NodeJS.ProcessEnv,
+ homeDir: string,
+ cwd: string = process.cwd(),
+ platform: string = process.platform,
+): Layer[] {
+ const layers: Layer[] = [];
+
+ for (const managed of managedSettingsPaths(platform)) {
+ const value = envBlockUrl(managed);
+ if (value) layers.push({ source: `${managed} (MANAGED env block)`, value, effective: false });
+ }
+
+ for (const file of [
+ path.join(cwd, '.claude', 'settings.local.json'),
+ path.join(cwd, '.claude', 'settings.json'),
+ // CLAUDE_CONFIG_DIR relocates the user scope wholesale; missing it reads
+ // a settings file the running tool never opens.
+ path.join(env.CLAUDE_CONFIG_DIR ?? path.join(homeDir, '.claude'), 'settings.json'),
+ ]) {
+ const value = envBlockUrl(file);
+ if (value) layers.push({ source: `${file} (env block)`, value, effective: false });
+ }
+
+ if (env.ANTHROPIC_BASE_URL) {
+ layers.push({
+ source: 'ANTHROPIC_BASE_URL (process environment)',
+ value: env.ANTHROPIC_BASE_URL,
+ effective: false,
+ });
+ }
+
+ if (layers.length) layers[0].effective = true;
+ return layers;
+}
+
+/**
+ * Codex's base-URL layers, highest precedence first.
+ *
+ * Codex resolves a PROVIDER, not a URL: `model_provider` names a key in the
+ * `[model_providers]` table and that entry carries base_url. Reading only
+ * `base_url` occurrences would report a provider the user is not selecting,
+ * so the selected name is resolved first.
+ */
+export function codexLayers(
+ env: NodeJS.ProcessEnv,
+ homeDir: string,
+): Layer[] {
+ const layers: Layer[] = [];
+ const configPath = path.join(env.CODEX_HOME ?? path.join(homeDir, '.codex'), 'config.toml');
+ let toml = '';
+ try {
+ toml = fs.existsSync(configPath) ? fs.readFileSync(configPath, 'utf8') : '';
+ } catch {
+ toml = '';
+ }
+
+ const selected = /^\s*model_provider\s*=\s*["']([^"']+)["']/m.exec(toml)?.[1];
+ if (selected) {
+ // Both spellings the file format allows: a dotted key and a section.
+ const dotted = new RegExp(
+ `^\\s*model_providers\\.${escapeRegExp(selected)}\\.base_url\\s*=\\s*["']([^"']+)["']`,
+ 'm',
+ ).exec(toml)?.[1];
+ const section = sectionValue(toml, `model_providers.${selected}`, 'base_url');
+ const url = dotted ?? section;
+ if (url) {
+ layers.push({
+ source: `${configPath} ([model_providers.${selected}] base_url)`,
+ value: url,
+ effective: false,
+ });
+ } else {
+ layers.push({
+ source: `${configPath} (model_provider = "${selected}", no base_url found)`,
+ effective: false,
+ });
+ }
+ }
+
+ if (layers.length) layers[0].effective = true;
+ return layers;
+}
+
+function escapeRegExp(value: string): string {
+ return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Value of `key` inside a `[section]` block of a TOML document. */
+function sectionValue(toml: string, section: string, key: string): string | undefined {
+ const lines = toml.split('\n');
+ let inSection = false;
+ for (const raw of lines) {
+ const line = raw.trim();
+ const header = /^\[([^\]]+)\]$/.exec(line);
+ if (header) {
+ inSection = header[1].trim() === section;
+ continue;
+ }
+ if (!inSection) continue;
+ const match = new RegExp(`^${escapeRegExp(key)}\\s*=\\s*["']([^"']+)["']`).exec(line);
+ if (match) return match[1];
+ }
+ return undefined;
+}
+
+/** How long the /livez probe waits before calling an endpoint unreachable. */
+export const DEFAULT_PROBE_TIMEOUT_MS = 5_000;
+
+/**
+ * Probe a base URL's identity AND its health — two separate questions that must
+ * not be collapsed.
+ *
+ * IDENTITY is structural: `/livez` answers `{status, version, uptime_s}` and
+ * carries NO product identifier, so a body with that exact shape is evidence,
+ * not proof — another service could serve the same three keys. `identified`
+ * therefore means "responds the way this gateway responds", and the report says
+ * so. Asserting identity harder would need either an authenticated call (the
+ * CLI does not have a key here) or a product marker the server does not emit.
+ *
+ * HEALTH is the `status` VALUE, and it is deliberately not folded into
+ * identity. The server really does emit `{status: 'unavailable', ...}` with a
+ * 503 when the database or the encryption key is down (routes/status.ts), and
+ * that response is still unmistakably this gateway. Requiring `status === 'ok'`
+ * to identify it would report a correctly-routed but sick gateway as "probably
+ * a different service on that port" — the confident wrong answer this command
+ * exists to prevent. Anything that is not a 2xx `'ok'` is reported as
+ * unhealthy and the raw status is echoed, so a status added later degrades into
+ * a truthful "reaches this gateway, which says: <status>" instead of a lie.
+ */
+export async function probeGateway(
+ baseUrl: string,
+ fetchImpl: typeof fetch = fetch,
+ timeoutMs: number = DEFAULT_PROBE_TIMEOUT_MS,
+): Promise<GatewayProbe> {
+ let response: Response;
+ try {
+ response = await fetchImpl(`${normalizeUrl(baseUrl)}/livez`, {
+ signal: AbortSignal.timeout(timeoutMs),
+ });
+ } catch (error) {
+ return {
+ reachable: false,
+ identified: false,
+ healthy: false,
+ error: error instanceof Error ? error.message : String(error),
+ };
+ }
+ let body: Record<string, unknown> = {};
+ try {
+ body = await response.json() as Record<string, unknown>;
+ } catch {
+ return {
+ reachable: true,
+ identified: false,
+ healthy: false,
+ status: response.status,
+ error: 'response was not JSON',
+ };
+ }
+ const serviceStatus = typeof body.status === 'string' ? body.status : undefined;
+ const identified = serviceStatus !== undefined
+ && typeof body.version === 'string'
+ && typeof body.uptime_s === 'number';
+ return {
+ reachable: true,
+ identified,
+ healthy: identified && serviceStatus === 'ok' && response.status >= 200 && response.status < 300,
+ serviceStatus,
+ status: response.status,
+ version: typeof body.version === 'string' ? body.version : undefined,
+ };
+}
+
+export interface DoctorOptions {
+ /** The gateway the user believes they are using (--url / FREELLMAPI_URL). */
+ expectedUrl: string;
+ env?: NodeJS.ProcessEnv;
+ homeDir?: string;
+ /** Project-scoped settings are resolved relative to this. */
+ cwd?: string;
+ fetchImpl?: typeof fetch;
+ /** Probe timeout. Raise it on a slow link, where the default would report a
+ * reachable gateway as unreachable. */
+ timeoutMs?: number;
+}
+
+const LAYER_RESOLVERS: Record<string, (env: NodeJS.ProcessEnv, homeDir: string, cwd: string) => Layer[]> = {
+ claude: (env, homeDir, cwd) => claudeLayers(env, homeDir, cwd),
+ codex: (env, homeDir) => codexLayers(env, homeDir),
+};
+
+export const DOCTOR_TOOLS = Object.keys(LAYER_RESOLVERS);
+
+export async function diagnose(tool: string, options: DoctorOptions): Promise<ToolReport> {
+ const env = options.env ?? process.env;
+ const homeDir = options.homeDir ?? os.homedir();
+ const resolve = LAYER_RESOLVERS[tool];
+ if (!resolve) {
+ return {
+ tool,
+ verdict: 'unknown',
+ layers: [],
+ detail: `doctor does not know how ${tool} resolves its endpoint. Known tools: ${DOCTOR_TOOLS.join(', ')}.`,
+ };
+ }
+
+ const layers = resolve(env, homeDir, options.cwd ?? process.cwd());
+ const effective = layers.find(layer => layer.effective);
+
+ if (!effective?.value) {
+ return {
+ tool,
+ verdict: 'unknown',
+ layers,
+ detail: layers.length
+ ? 'A configuration layer was found but names no base URL, so the tool falls back to its vendor default.'
+ : `No configuration found. ${tool} will use its vendor default endpoint, not this gateway.`,
+ };
+ }
+
+ const gateway = await probeGateway(effective.value, options.fetchImpl, options.timeoutMs);
+
+ // A lower-precedence layer naming a DIFFERENT url is the silent-override
+ // case: the user edited that file and something outranks it.
+ const overridden = layers.find(
+ layer => !layer.effective && layer.value && !sameGateway(layer.value, effective.value),
+ );
+
+ if (!gateway.reachable) {
+ return {
+ tool,
+ verdict: 'unreachable',
+ layers,
+ effectiveUrl: effective.value,
+ gateway,
+ detail: `${tool} is configured to use ${effective.value}, but nothing answered there (${gateway.error}).`,
+ };
+ }
+
+ if (overridden) {
+ return {
+ tool,
+ verdict: 'shadowed',
+ layers,
+ effectiveUrl: effective.value,
+ shadowedBy: effective.source,
+ gateway,
+ detail:
+ `${overridden.source} sets ${overridden.value}, but ${effective.source} outranks it, `
+ + `so ${tool} actually uses ${effective.value}.`,
+ };
+ }
+
+ // Two distinct ways to be pointed somewhere else, and both must fail the
+ // check: a different host entirely, or the right host answering nothing that
+ // looks like this gateway.
+ if (!sameGateway(effective.value, options.expectedUrl)) {
+ return {
+ tool,
+ verdict: 'elsewhere',
+ layers,
+ effectiveUrl: effective.value,
+ gateway,
+ detail:
+ `${tool} reaches ${effective.value}, NOT the ${options.expectedUrl} this command was pointed at. `
+ + 'Its traffic does not touch this gateway.',
+ };
+ }
+
+ if (!gateway.identified) {
+ return {
+ tool,
+ verdict: 'elsewhere',
+ layers,
+ effectiveUrl: effective.value,
+ gateway,
+ detail:
+ `Something is listening at ${effective.value} and ${tool} would reach it, but it did not answer `
+ + '/livez the way this gateway does — so it is probably a different service on that port.',
+ };
+ }
+
+ // Routing is correct here and the gateway is unmistakably this one — it just
+ // says it cannot serve. Reporting that as `routed` would send the user
+ // hunting through config that is already right, so it gets its own verdict
+ // and a nonzero exit.
+ if (!gateway.healthy) {
+ return {
+ tool,
+ verdict: 'degraded',
+ layers,
+ effectiveUrl: effective.value,
+ gateway,
+ detail:
+ `${tool} reaches ${effective.value} and that IS this gateway, but it reports `
+ + `status "${gateway.serviceStatus}" (HTTP ${gateway.status}) — it cannot serve requests. `
+ + 'The routing is fine; the gateway is not.',
+ };
+ }
+
+ return {
+ tool,
+ verdict: 'routed',
+ layers,
+ effectiveUrl: effective.value,
+ gateway,
+ detail: `${tool} reaches ${effective.value}${gateway.version ? ` (gateway v${gateway.version})` : ''}.`,
+ };
+}
+
+const SYMBOL: Record<Verdict, string> = {
+ routed: 'OK ',
+ degraded: 'WARN',
+ elsewhere: 'FAIL',
+ shadowed: 'WARN',
+ unreachable: 'FAIL',
+ unknown: '? ',
+};
+
+export function formatReport(report: ToolReport): string {
+ const lines = [`${SYMBOL[report.verdict]} ${report.tool}: ${report.verdict}`, ` ${report.detail}`];
+ for (const layer of report.layers) {
+ lines.push(` ${layer.effective ? '->' : ' '} ${layer.source}${layer.value ? ` = ${layer.value}` : ''}`);
+ }
+ if (report.gateway?.reachable && !report.gateway.identified) {
+ lines.push(' note: something answered, but not with this gateway\'s /livez shape.');
+ }
+ return lines.join('\n');
+}
+
+/** Exit code: 0 when every tool is routed, 1 otherwise — so it is usable in a
+ * script, not only by eye. */
+export function exitCodeFor(reports: ToolReport[]): number {
+ return reports.every(report => report.verdict === 'routed') ? 0 : 1;
+}
diff --git a/cli/src/index.test.ts b/cli/src/index.test.ts
index 6fd96334..341f46fb 100644
--- a/cli/src/index.test.ts
+++ b/cli/src/index.test.ts
@@ -2,7 +2,7 @@ import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { afterEach, describe, expect, it } from 'vitest';
-import { claudeLaunchEnv, codexArgs, parseArgs, resolvePinnedModel } from './index.js';
+import { claudeLaunchEnv, codexArgs, main, parseArgs, resolvePinnedModel } from './index.js';
import { UnknownModelError } from './models.js';
import type { CatalogModel } from './types.js';
@@ -36,6 +36,28 @@ describe('CLI arguments and launchers', () => {
.toThrow('--profile requires a value');
});
+ it('parses doctor --timeout, and rejects a value that is not milliseconds', () => {
+ expect(parseArgs(['doctor', '--timeout', '30000']).options.timeoutMs).toBe(30_000);
+ expect(parseArgs(['doctor', '--timeout=250']).options.timeoutMs).toBe(250);
+ // Left undefined rather than defaulted here, so doctor.ts owns the default.
+ expect(parseArgs(['doctor']).options.timeoutMs).toBeUndefined();
+ // Rejected, not silently ignored: a typo quietly becoming the default is
+ // exactly the quiet no-op this command exists to catch.
+ expect(() => parseArgs(['doctor', '--timeout', '5s'])).toThrow('positive number of milliseconds');
+ expect(() => parseArgs(['doctor', '--timeout', '0'])).toThrow('positive number of milliseconds');
+ });
+
+ it('still rejects a stray positional for commands that take none', async () => {
+ // `doctor` is the only command with positional arguments, so parseArgs
+ // collects them generically. The dispatcher has to reject them for every
+ // other command BEFORE dispatch — checked after the setup-* branch, the
+ // stray word would be silently ignored instead of erroring.
+ await expect(main(['setup-claude', 'typo'])).rejects.toThrow('Unknown option: typo');
+ await expect(main(['launch', 'typo'])).rejects.toThrow('Unknown option: typo');
+ // ...and doctor still takes them.
+ expect(parseArgs(['doctor', 'claude']).options.args).toEqual(['claude']);
+ });
+
const models: CatalogModel[] = [
{ id: 'auto' },
{ id: 'fast-coder', available: true, context_window: 131072 },
diff --git a/cli/src/index.ts b/cli/src/index.ts
index 372a74a2..a02e8c82 100644
--- a/cli/src/index.ts
+++ b/cli/src/index.ts
@@ -10,6 +10,7 @@ import { fileURLToPath } from 'node:url';
import { applyGeneratedFiles, printDryRunDiff } from './config-files.js';
import { getTool, tools } from './tools.js';
import { resolveLaunchModel, type ResolvedModel } from './models.js';
+import { DOCTOR_TOOLS, diagnose, exitCodeFor, formatReport, type ToolReport } from './doctor.js';
import type { CatalogModel, GenerateContext } from './types.js';
interface CliOptions {
@@ -18,6 +19,11 @@ interface CliOptions {
profile: string;
model?: string;
dryRun: boolean;
+ /** `doctor --timeout`: how long to wait for the /livez probe. */
+ timeoutMs?: number;
+ /** Positional arguments after the command. Only `doctor` takes any; every
+ * other command still rejects a second positional as it always has. */
+ args: string[];
}
function rootUrl(url: string): string {
@@ -37,12 +43,24 @@ function validateProfile(profile: string): string {
return profile;
}
+function parseTimeout(value: string): number {
+ const ms = Number(value);
+ // Rejected rather than clamped: a typo'd `--timeout 5s` parsing to NaN and
+ // silently becoming the default is the kind of quiet no-op this command is
+ // supposed to be immune to.
+ if (!Number.isFinite(ms) || ms <= 0) {
+ throw new Error(`--timeout must be a positive number of milliseconds, got '${value}'`);
+ }
+ return ms;
+}
+
export function parseArgs(argv: string[]): { command?: string; options: CliOptions } {
const options: CliOptions = {
url: process.env.FREELLMAPI_URL || 'http://localhost:3000',
apiKey: process.env.FREELLMAPI_API_KEY,
profile: 'default',
dryRun: false,
+ args: [],
};
let command: string | undefined;
for (let index = 0; index < argv.length; index += 1) {
@@ -51,13 +69,23 @@ export function parseArgs(argv: string[]): { command?: string; options: CliOptio
command = arg;
continue;
}
+ if (!arg.startsWith('-')) {
+ // Collected rather than rejected here so the parser stays generic; the
+ // dispatcher rejects extras for commands that take none, which keeps
+ // `setup-claude typo` an error instead of a silently ignored word.
+ options.args.push(arg);
+ continue;
+ }
if (arg === '--dry-run') {
options.dryRun = true;
continue;
}
const [flag, inline] = arg.split('=', 2);
const value = inline ?? argv[index + 1];
- if (flag === '--url' || flag === '--api-key' || flag === '--profile' || flag === '--model') {
+ if (
+ flag === '--url' || flag === '--api-key' || flag === '--profile'
+ || flag === '--model' || flag === '--timeout'
+ ) {
if (inline === undefined) index += 1;
if (!value || (inline === undefined && value.startsWith('-'))) {
throw new Error(`${flag} requires a value`);
@@ -65,6 +93,7 @@ export function parseArgs(argv: string[]): { command?: string; options: CliOptio
if (flag === '--url') options.url = value;
else if (flag === '--api-key') options.apiKey = value;
else if (flag === '--profile') options.profile = validateProfile(value);
+ else if (flag === '--timeout') options.timeoutMs = parseTimeout(value);
else options.model = value;
continue;
}
@@ -214,6 +243,8 @@ function help(): string {
'',
'Commands:',
...tools.map(tool => ` ${tool.command.padEnd(17)} ${tool.name}`),
+ ' doctor [tool…] Check whether a tool\'s requests actually reach this gateway',
+ ' (--timeout MS raises the probe wait on a slow link)',
' launch Run Claude Code with credentials injected into the child environment',
' launch-codex Run Codex with provider overrides and injected credentials',
' list List supported coding agents',
@@ -380,12 +411,34 @@ async function launchCodex(options: CliOptions): Promise<number> {
return runChild('codex', args, env);
}
+async function runDoctor(options: CliOptions): Promise<number> {
+ const requested = options.args.length ? options.args : DOCTOR_TOOLS;
+ const reports: ToolReport[] = [];
+ for (const tool of requested) {
+ reports.push(await diagnose(tool, {
+ expectedUrl: rootUrl(options.url),
+ timeoutMs: options.timeoutMs,
+ }));
+ }
+ for (const report of reports) process.stdout.write(`${formatReport(report)}\n`);
+ // Nonzero when anything is not routed, so this is usable as a precondition
+ // in a script rather than only readable by eye.
+ return exitCodeFor(reports);
+}
+
export async function main(argv = process.argv.slice(2)): Promise<number> {
const { command, options } = parseArgs(argv);
if (!command || command === 'help' || argv.includes('--help') || argv.includes('-h')) {
process.stdout.write(`${help()}\n`);
return 0;
}
+ // `doctor` is the only command that takes positional arguments. Every other
+ // one rejects them here, BEFORE dispatch — checking after the setup-* branch
+ // would let `setup-claude typo` run with the stray word silently ignored,
+ // where it used to be an error.
+ if (command !== 'doctor' && options.args.length) {
+ throw new Error(`Unknown option: ${options.args[0]}`);
+ }
if (command === 'list') {
for (const tool of tools) {
process.stdout.write(`${tool.id}\t${tool.protocol}\t${tool.baseUrlSupport}\n`);
@@ -396,6 +449,7 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {
await setup(command, options);
return 0;
}
+ if (command === 'doctor') return runDoctor(options);
if (command === 'launch') return launchClaude(options);
if (command === 'launch-codex') return launchCodex(options);
throw new Error(`Unknown command '${command}'\n\n${help()}`);