Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(open-knowledge): bind autostarted server to 127.0.0.1, not localhost (PRD-7259) (#2389)
mike-inkeepbe8195b097e4
diff --git a/.changeset/windows-ipv4-loopback-bind.md b/.changeset/windows-ipv4-loopback-bind.mdnew file mode 100644index 000000000..4072c6c45--- /dev/null+++ b/.changeset/windows-ipv4-loopback-bind.md@@ -0,0 +1,13 @@+---+"@inkeep/open-knowledge": patch+---++Fix the server being unreachable on Windows when your coding agent auto-starts+it over MCP. The server used to bind the `localhost` hostname, which Windows+resolves to IPv6 (`::1`) only, while the tools connecting to it use IPv4+(`127.0.0.1`) — so `edit` / `exec` calls failed with "Server unreachable: fetch+failed". The server now binds numeric `127.0.0.1` directly (still loopback-only),+and the MCP shim and the `ok ui` proxy connect to the same address, so there is+no longer any IPv4/IPv6 mismatch on any platform. You no longer need the+`--host 127.0.0.1` / `HOST=127.0.0.1` workaround. macOS and Linux behavior is+unchanged.diff --git a/packages/cli/src/commands/start.test.ts b/packages/cli/src/commands/start.test.tsindex 91e93b903..1381ab685 100644--- a/packages/cli/src/commands/start.test.ts+++ b/packages/cli/src/commands/start.test.ts@@ -41,8 +41,8 @@ describe('resolveHost', () => {expect(resolveHost({}, { HOST: '0.0.0.0' })).toBe('0.0.0.0');});- test('falls back to DEFAULT_SERVER_HOST (localhost) when both flag and env are absent', () => {- expect(resolveHost({}, {})).toBe('localhost');+ test('falls back to DEFAULT_SERVER_HOST (numeric IPv4 loopback) when both flag and env are absent', () => {+ expect(resolveHost({}, {})).toBe('127.0.0.1');});test('explicit undefined --host falls through to env (precedence: flag > env > default)', () => {diff --git a/packages/cli/src/commands/ui.ts b/packages/cli/src/commands/ui.tsindex 4aea32dcf..a7f6cd636 100644--- a/packages/cli/src/commands/ui.ts+++ b/packages/cli/src/commands/ui.ts@@ -1,6 +1,7 @@import type { Server as HttpServer, ServerResponse } from 'node:http';import {ASSET_EXTENSIONS,+ DEFAULT_SERVER_HOST,defaultScheduler,EXECUTABLE_BLOCKLIST_EXTENSIONS,INLINE_RENDERABLE_EXTENSIONS,@@ -177,7 +178,7 @@ export async function startUiServer(opts: StartUiServerOptions): Promise<UiServereturn;}proxyRequest(req, res, {- upstreamHost: 'localhost',+ upstreamHost: DEFAULT_SERVER_HOST,upstreamPort: lock.port,});return;@@ -237,7 +238,14 @@ export async function startUiServer(opts: StartUiServerOptions): Promise<UiServeclientSocket.destroy();return;}- proxyUpgrade(req, clientSocket, head, 'localhost', lock.port, upgradeSocketsForShutdown);+ proxyUpgrade(+ req,+ clientSocket,+ head,+ DEFAULT_SERVER_HOST,+ lock.port,+ upgradeSocketsForShutdown,+ );};const drainUpgradeSockets = (): void => {for (const sock of upgradeSocketsForShutdown) {diff --git a/packages/cli/src/mcp/shim.test.ts b/packages/cli/src/mcp/shim.test.tsindex 2f938d8c3..3e16ed918 100644--- a/packages/cli/src/mcp/shim.test.ts+++ b/packages/cli/src/mcp/shim.test.ts@@ -91,7 +91,7 @@ describe('MCP stdio shim server resolution', () => {}) as never,});- expect(url).toBe('http://localhost:4123/mcp');+ expect(url).toBe('http://127.0.0.1:4123/mcp');});test('missing lock spawns ok start and polls until a live port appears', async () => {@@ -126,7 +126,7 @@ describe('MCP stdio shim server resolution', () => {pollIntervalMs: 1,});- expect(url).toBe('http://localhost:4123/mcp');+ expect(url).toBe('http://127.0.0.1:4123/mcp');expect(calls).toHaveLength(1);expect(calls[0]?.cmd).toBe(process.execPath);expect(calls[0]?.args.at(-1)).toBe('start');@@ -146,7 +146,7 @@ describe('MCP stdio shim server resolution', () => {expect((err as Error).message).toContain('OK_MCP_AUTOSTART=0');});- test('valid port override bypasses discovery and formats wildcard host as localhost', async () => {+ test('valid port override bypasses discovery and targets the default loopback host', async () => {const url = await resolveMcpHttpUrl({lockDir,contentDir: tmp,@@ -160,7 +160,7 @@ describe('MCP stdio shim server resolution', () => {}) as never,});- expect(url).toBe('http://localhost:6789/mcp');+ expect(url).toBe('http://127.0.0.1:6789/mcp');});test('invalid port override rejects before spawn', async () => {@@ -261,7 +261,7 @@ describe('MCP stdio shim server resolution', () => {},'http://localhost:4123/mcp',),- ).toBe('ws://localhost:4123');+ ).toBe('ws://127.0.0.1:4123');expect(resolveMcpKeepaliveWsUrl(diff --git a/packages/cli/src/mcp/shim.ts b/packages/cli/src/mcp/shim.tsindex a33987c79..51f489473 100644--- a/packages/cli/src/mcp/shim.ts+++ b/packages/cli/src/mcp/shim.ts@@ -4,7 +4,11 @@ import { closeSync, existsSync, mkdirSync, openSync, readFileSync } from 'node:fimport { join } from 'node:path';import type { Readable, Writable } from 'node:stream';import { setTimeout as wait } from 'node:timers/promises';-import { clientVersionHeaders, SPAWN_ERROR_LOG } from '@inkeep/open-knowledge-core';+import {+ clientVersionHeaders,+ DEFAULT_SERVER_HOST,+ SPAWN_ERROR_LOG,+} from '@inkeep/open-knowledge-core';import { startKeepalive as defaultStartKeepalive } from '@inkeep/open-knowledge-core/keepalive';import {AutoStartDisabledError,@@ -184,11 +188,11 @@ export async function resolveMcpHttpUrl(opts: ResolveMcpHttpUrlOptions): Promise`invalid --port value '${opts.portOverride}' — HTTP MCP shim requires a positive port`,);}- return mcpUrlForPort('localhost', parsed);+ return mcpUrlForPort(DEFAULT_SERVER_HOST, parsed);}const existingPort = livePortFromLock(readLock(), isAlive);- if (existingPort !== undefined) return mcpUrlForPort('localhost', existingPort);+ if (existingPort !== undefined) return mcpUrlForPort(DEFAULT_SERVER_HOST, existingPort);if (opts.envAutoStart === '0') {throw new AutoStartDisabledError(@@ -237,7 +241,7 @@ export async function resolveMcpHttpUrl(opts: ResolveMcpHttpUrlOptions): Promise}await sleep(pollIntervalMs);const port = livePortFromLock(readLock(), isAlive);- if (port !== undefined) return mcpUrlForPort('localhost', port);+ if (port !== undefined) return mcpUrlForPort(DEFAULT_SERVER_HOST, port);}if (asyncSpawnError) {@@ -257,7 +261,7 @@ export function resolveMcpKeepaliveWsUrl(const readLock = opts.readLock ?? (() => readServerLock(opts.lockDir));const isAlive = opts.isAlive ?? defaultIsProcessAlive;const port = livePortFromLock(readLock(), isAlive);- if (port !== undefined) return wsUrlForPort('localhost', port);+ if (port !== undefined) return wsUrlForPort(DEFAULT_SERVER_HOST, port);return undefined;}diff --git a/packages/core/src/constants/server.ts b/packages/core/src/constants/server.tsindex b544a778b..3fc5ebf31 100644--- a/packages/core/src/constants/server.ts+++ b/packages/core/src/constants/server.ts@@ -1 +1 @@-export const DEFAULT_SERVER_HOST = 'localhost';+export const DEFAULT_SERVER_HOST = '127.0.0.1';