Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): serve content assets from every server by default (#2650)

Andrew Mikofalvyf99af3083818
diff --git a/.changeset/serve-content-assets-by-default.md b/.changeset/serve-content-assets-by-default.md
new file mode 100644
index 000000000..a6a3fbdf5
--- /dev/null
+++ b/.changeset/serve-content-assets-by-default.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Inline images now render in desktop windows attached to a server the desktop did not spawn (MCP-autostarted or terminal `ok start`). Every server now serves content-directory assets (images, video, audio, PDF, file attachments) at their `/<contentDir-relative>` paths by default, through the same admission middleware `ok ui` uses (inline/attachment dispatch, fail-closed 404 for missing assets). Previously only desktop-spawned servers passed `--serve-content-assets`, so a desktop window attaching to an MCP-spawned server resolved image srcs against an origin that 404'd them, showing broken images for every inline image in the project. The flag is still accepted for compatibility; pass `serveContentAssets: false` to `bootServer` to opt out. Servers that don't serve the React shell keep the `ok ui` pointer hint in their catch-all 404.
diff --git a/packages/cli/src/commands/start.test.ts b/packages/cli/src/commands/start.test.ts
index 7ee52e3c7..fbb1fa116 100644
--- a/packages/cli/src/commands/start.test.ts
+++ b/packages/cli/src/commands/start.test.ts
@@ -1213,13 +1213,16 @@ describe('bootStartServer (integration)', () => {
for (const c of captured) expect(c.reclaimDisableEnv).toBeNull();
});
- // --- single-origin opt-ins (--serve-content-assets, --react-shell-dist-dir) ---
+ // --- content-asset serving (default-on) + --react-shell-dist-dir opt-in ---
- test('serveContentAssets: false (default) — content paths return the SPA-pointer 404', async () => {
- // Pre-seed a real asset in the content directory. With serveContentAssets
- // off, the server has no /<contentDir-relative> middleware and the request
- // falls through to the "React UI is served by `ok ui`" pointer.
- writeFileSync(join(tmpDir, 'fixture-asset.png'), 'fake-png-bytes', 'utf-8');
+ test('default — content assets are served from the server origin', async () => {
+ // Nested path mirrors the attach-mode desktop shape: the renderer rewrites
+ // `/<contentDir-relative>` inline-image srcs onto the lock holder's origin,
+ // so a server booted with NO flags (MCP-autostarted, terminal `ok start`)
+ // must serve them or attached windows render broken images.
+ const assetBytes = `fake-png-bytes-${Math.random()}`;
+ mkdirSync(join(tmpDir, 'specs', 'nested'), { recursive: true });
+ writeFileSync(join(tmpDir, 'specs', 'nested', 'mockup.png'), assetBytes, 'utf-8');
booted = await bootStartServer({
config: makeTestConfig(),
@@ -1229,18 +1232,18 @@ describe('bootStartServer (integration)', () => {
skipUiAutoSpawn: true,
});
- const res = await fetchText(booted.port, '/fixture-asset.png');
- expect(res.status).toBe(404);
- const body = JSON.parse(res.body);
- expect(body.detail).toContain('React UI is served by `ok ui`');
+ const res = await fetchText(booted.port, '/specs/nested/mockup.png');
+ expect(res.status).toBe(200);
+ expect(res.body).toBe(assetBytes);
+ // PNGs are inline-renderable; Content-Disposition should be inline.
+ const disposition = res.headers['content-disposition'];
+ expect(typeof disposition === 'string' ? disposition : '').toContain('inline');
});
- test('serveContentAssets: true — content asset is served from the server origin', async () => {
- // Real fixture; serveContentAssets installs createAssetServeMiddleware
- // over the content directory, so the same path now returns 200 with the
- // file bytes (Content-Disposition: inline for image extensions).
- const assetBytes = `fake-png-bytes-${Math.random()}`;
- writeFileSync(join(tmpDir, 'fixture-asset.png'), assetBytes, 'utf-8');
+ test('serveContentAssets: false — content paths return the SPA-pointer 404', async () => {
+ // Explicit opt-out: no /<contentDir-relative> middleware, so the request
+ // falls through to the "React UI is served by `ok ui`" pointer.
+ writeFileSync(join(tmpDir, 'fixture-asset.png'), 'fake-png-bytes', 'utf-8');
booted = await bootStartServer({
config: makeTestConfig(),
@@ -1248,15 +1251,13 @@ describe('bootStartServer (integration)', () => {
host: TEST_HOST,
skipAutoInit: true,
skipUiAutoSpawn: true,
- serveContentAssets: true,
+ serveContentAssets: false,
});
const res = await fetchText(booted.port, '/fixture-asset.png');
- expect(res.status).toBe(200);
- expect(res.body).toBe(assetBytes);
- // PNGs are inline-renderable; Content-Disposition should be inline.
- const disposition = res.headers['content-disposition'];
- expect(typeof disposition === 'string' ? disposition : '').toContain('inline');
+ expect(res.status).toBe(404);
+ const body = JSON.parse(res.body);
+ expect(body.detail).toContain('React UI is served by `ok ui`');
});
test('reactShellDistDir — server serves the shell on /, auto-suppresses ok ui sibling', async () => {
diff --git a/packages/cli/src/commands/start.ts b/packages/cli/src/commands/start.ts
index add4d2876..368db5f98 100644
--- a/packages/cli/src/commands/start.ts
+++ b/packages/cli/src/commands/start.ts
@@ -691,14 +691,15 @@ interface BootStartServerOptions {
logger?: (event: { event: string }) => void;
}) => Promise<unknown> | unknown;
/**
- * When `true`, the server serves content-directory assets
- * (images/video/PDF/file attachments) at their `/<contentDir-relative>`
- * paths via `createAssetServeMiddleware` — matching the Vite dev plugin
- * and `ok ui`. Off by default — terminal-launched `ok start` relies on
- * the `ok ui` sibling for asset serving. The OpenKnowledge desktop
- * passes this when spawning the detached server so its renderer can
- * fetch assets from the same origin as `/api/*` and `/collab*`. Forwards
- * directly to `BootServerOptions.serveContentAssets`.
+ * When `true` (the `bootServer` default), the server serves
+ * content-directory assets (images/video/PDF/file attachments) at their
+ * `/<contentDir-relative>` paths via `createAssetServeMiddleware` —
+ * matching the Vite dev plugin and `ok ui`. On by default so a desktop
+ * window that ATTACHES to this server (MCP-autostarted or terminal
+ * `ok start` — its renderer fetches assets from the same origin as
+ * `/api/*` and `/collab*`) renders inline images; the `ok ui` sibling
+ * still serves assets for browser mode. Forwards directly to
+ * `BootServerOptions.serveContentAssets`.
*/
serveContentAssets?: boolean;
/**
@@ -1041,9 +1042,12 @@ export async function bootStartServer(opts: BootStartServerOptions): Promise<Boo
return withIdleShutdownProcessExit(reaped, { log, exit: opts.idleExit });
},
log,
- // Single-origin opt-ins for desktop-spawned servers. Forwarded only
- // when set so terminal `ok start` retains today's two-process behavior.
- ...(opts.serveContentAssets ? { serveContentAssets: true } : {}),
+ // Content assets serve by default (bootServer default-on); the React
+ // shell stays a desktop-spawn opt-in so terminal `ok start` retains the
+ // two-process shell model (`ok ui` sibling).
+ ...(opts.serveContentAssets !== undefined
+ ? { serveContentAssets: opts.serveContentAssets }
+ : {}),
...(opts.reactShellDistDir ? { reactShellDistDir: opts.reactShellDistDir } : {}),
});
@@ -1114,7 +1118,11 @@ interface StartCommandOptions {
open?: boolean;
/** From `--mode`: undefined (default → browser) | 'browser' | 'app'. */
mode?: StartMode;
- /** From `--serve-content-assets`. See `BootStartServerOptions.serveContentAssets`. */
+ /**
+ * From `--serve-content-assets`. Redundant now that `bootServer` defaults
+ * the surface on; accepted for compatibility with older desktop spawners
+ * that still pass the flag. See `BootStartServerOptions.serveContentAssets`.
+ */
serveContentAssets?: boolean;
/** From `--react-shell-dist-dir <path>`. See `BootStartServerOptions.reactShellDistDir`. */
reactShellDistDir?: string;
@@ -1260,7 +1268,9 @@ export async function runStartCommand(config: Config, opts: StartCommandOptions)
host,
port,
...(requestedUiPort !== undefined ? { uiPort: requestedUiPort } : {}),
- ...(opts.serveContentAssets ? { serveContentAssets: true } : {}),
+ ...(opts.serveContentAssets !== undefined
+ ? { serveContentAssets: opts.serveContentAssets }
+ : {}),
...(opts.reactShellDistDir ? { reactShellDistDir: opts.reactShellDistDir } : {}),
...(opts.singleFile ? { singleFile: opts.singleFile } : {}),
...(opts.projectDir ? { projectDir: opts.projectDir } : {}),
@@ -1471,7 +1481,10 @@ export function startCommand(getConfig: () => Config): Command {
.option('-H, --host <host>', 'Server host', undefined)
.option('--open', 'Open browser after start')
.option('--mode <mode>', "Force dispatch mode: 'browser' or 'app'", parseStartMode)
- .option('--serve-content-assets', 'Serve content assets from this server')
+ .option(
+ '--serve-content-assets',
+ 'Serve content assets from this server (now the default; kept for compatibility)',
+ )
.option(
'--react-shell-dist-dir <path>',
'Serve React shell from <path> (suppresses ok ui sibling)',
diff --git a/packages/server/src/boot.ts b/packages/server/src/boot.ts
index 95082dc4a..8865647d5 100644
--- a/packages/server/src/boot.ts
+++ b/packages/server/src/boot.ts
@@ -238,17 +238,20 @@ export interface BootServerOptions
/**
* Serve content-directory assets (images / video / audio / PDF / file
* attachments) over this HTTP server, mirroring the `bun run dev` Vite
- * plugin and `ok ui`. Default `false`.
+ * plugin and `ok ui`. Default `true`; pass `false` to opt out (tests
+ * that pin the no-middleware surface).
*
- * The Electron utility sets this `true`: the BrowserWindow renderer
- * page origin (a Vite dev URL or a `file://` path) has no asset middleware,
- * so server-absolute `/<contentDir-relative>` image srcs can't resolve
- * there. With this on, the renderer rewrites those srcs onto
- * `window.okDesktop.config.apiOrigin` (the utility server's origin), which
- * serves them via `createAssetServeMiddleware` — the canonical primitive,
- * so the inline/attachment policy + fail-closed 404 guard come for free.
- * The CLI leaves it `false` — `ok ui` already serves content assets on its
- * own port.
+ * Default-on because the desktop renderer resolves server-absolute
+ * `/<contentDir-relative>` image srcs against
+ * `window.okDesktop.config.apiOrigin`, and attach-mode treats lock kind as
+ * provenance-only — the desktop attaches to servers it did not spawn
+ * (MCP-autostarted, user-run `ok start`). Every attachable server must
+ * therefore expose the content-asset surface, or inline images 404 in
+ * attach-mode windows. Serving is additive: the same bytes are already
+ * reachable via `/api/asset`, and `createAssetServeMiddleware` — the
+ * canonical primitive — brings the inline/attachment policy + fail-closed
+ * 404 guard. `ok ui` continues to serve content assets on its own port for
+ * browser mode; the React shell (`reactShellDistDir`) stays opt-in.
*/
serveContentAssets?: boolean;
/**
@@ -682,19 +685,22 @@ async function bootServerInner(opts: BootServerOptions): Promise<BootedServer> {
httpServer.headersTimeout = 30_000;
httpServer.requestTimeout = 60_000;
- // Content-asset serving — desktop mode only. Reuses the canonical
+ // Content-asset serving — default-on for every boot path so attach-mode
+ // desktop windows resolve inline-image srcs against any lock holder (see
+ // the `serveContentAssets` option doc). Reuses the canonical
// `createAssetServeMiddleware` (STOP rule: serve-side asset admission goes
// through this factory) so the inline/attachment Content-Disposition policy
// + fail-closed 404 guard match the Vite dev plugin and `ok ui`.
- const contentAssetMiddleware = opts.serveContentAssets
- ? createAssetServeMiddleware({
- contentFilter: serverInstance.contentFilter,
- contentSirv: sirv(opts.contentDir, { dev: true, dotfiles: false }),
- inlineExtensions: INLINE_RENDERABLE_EXTENSIONS,
- assetExtensions: ASSET_EXTENSIONS,
- blocklistExtensions: EXECUTABLE_BLOCKLIST_EXTENSIONS,
- })
- : undefined;
+ const contentAssetMiddleware =
+ opts.serveContentAssets !== false
+ ? createAssetServeMiddleware({
+ contentFilter: serverInstance.contentFilter,
+ contentSirv: sirv(opts.contentDir, { dev: true, dotfiles: false }),
+ inlineExtensions: INLINE_RENDERABLE_EXTENSIONS,
+ assetExtensions: ASSET_EXTENSIONS,
+ blocklistExtensions: EXECUTABLE_BLOCKLIST_EXTENSIONS,
+ })
+ : undefined;
// When serving the React shell, try to advertise via `ui.lock` so external
// preview-URL consumers find our port. If a live holder already owns the
diff --git a/packages/server/src/mcp-mount.ts b/packages/server/src/mcp-mount.ts
index da70f0977..d46fc019a 100644
--- a/packages/server/src/mcp-mount.ts
+++ b/packages/server/src/mcp-mount.ts
@@ -344,9 +344,17 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandl
runMiddleware(reactShellMiddleware, 'react-shell', onMiss);
const notFound = (): void => {
if (res.writableEnded || res.headersSent) return;
+ // When this server doesn't serve the React shell (CLI / MCP-spawned —
+ // content assets mount by default but the UI lives on the `ok ui`
+ // sibling), keep the operator hint so a human loading `/` in a browser
+ // is pointed at the right port.
+ const uiHint =
+ reactShellMiddleware === undefined
+ ? 'The React UI is served by `ok ui` (run `ok ui` and check `ui.lock.port`). '
+ : '';
errorResponse(res, 404, 'urn:ok:error:not-found', 'Not found.', {
handler: 'mcp-mount',
- detail: `No handler for ${url ?? '/'}`,
+ detail: `${uiHint}No handler for ${url ?? '/'}`,
});
};