The best way to control Claude Code, Codex and more from any computer or phone
fix(server): explain fake-IP DNS failures in HTML previews (#30318)
shivam committed
Nov 6, 2026 at 09:57 UTC
b1f1731cabd5b22e84c742f53e11465058bd9e6e
4 files changed
+89
-20
apps/server/src/htmlRender/headlessChrome.ts
+28
-10
@@ -105,6 +105,15 @@ const decodeLogEntryAdded = Schema.decodeUnknownOption(
105
}),
106
);
107
108
+const clipConsoleText = (text: string) => {
109
+ if (text.length <= MAX_CONSOLE_TEXT_CHARS) return text;
110
+ // Half an emoji serializes to a lone surrogate escape, which provider JSON parsers reject.
111
+ const last = text.charCodeAt(MAX_CONSOLE_TEXT_CHARS - 1);
112
+ const end =
113
+ last >= 0xd800 && last <= 0xdbff ? MAX_CONSOLE_TEXT_CHARS - 1 : MAX_CONSOLE_TEXT_CHARS;
114
+ return `${text.slice(0, end)}…`;
115
+};
116
+
117
const remoteObjectText = (value: typeof RemoteObject.Type) =>
118
typeof value.value === "string"
119
? value.value
@@ -173,7 +182,7 @@ const launchBrowser = Effect.fnUntraced(function* (input: {
182
readonly profileDirectory: string;
183
}) {
184
const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
176
- const proxyPort = yield* publicProxy.pipe(
185
+ const proxy = yield* publicProxy.pipe(
186
Effect.mapError(
187
(cause) => new HtmlRenderBrowserError({ reason: "the preview proxy could not start", cause }),
188
),
@@ -192,7 +201,7 @@ const launchBrowser = Effect.fnUntraced(function* (input: {
201
"--hide-scrollbars",
202
"--mute-audio",
203
"--block-new-web-contents",
195
- `--proxy-server=socks5://127.0.0.1:${proxyPort}`,
204
+ `--proxy-server=socks5://127.0.0.1:${proxy.port}`,
205
// Loopback would otherwise skip the proxy.
206
"--proxy-bypass-list=<-loopback>",
207
// WebRTC would otherwise send UDP, which no proxy carries.
@@ -315,14 +324,9 @@ const launchBrowser = Effect.fnUntraced(function* (input: {
324
page.omittedConsoleMessages += 1;
325
return yield* Effect.void;
326
}
318
- const text = consoleMessage.text.replaceAll(PAGE_URL, PAGE_NAME);
319
- // Half an emoji serializes to a lone surrogate escape, which provider JSON parsers reject.
320
- const last = text.charCodeAt(MAX_CONSOLE_TEXT_CHARS - 1);
321
- const end =
322
- last >= 0xd800 && last <= 0xdbff ? MAX_CONSOLE_TEXT_CHARS - 1 : MAX_CONSOLE_TEXT_CHARS;
327
page.consoleMessages.push({
328
level: consoleMessage.level,
325
- text: text.length > MAX_CONSOLE_TEXT_CHARS ? `${text.slice(0, end)}…` : text,
329
+ text: clipConsoleText(consoleMessage.text.replaceAll(PAGE_URL, PAGE_NAME)),
330
});
331
return yield* Effect.void;
332
});
@@ -533,7 +537,16 @@ const launchBrowser = Effect.fnUntraced(function* (input: {
537
return { load, screenshot, consoleMessages, close };
538
});
539
536
- return { openPage };
540
+ // Each capture opens one page per browser, so this note belongs to that page alone.
541
+ const fakeIpNote = (): ReadonlyArray<ConsoleMessage> =>
542
+ [...proxy.fakeIpHosts].map(([host, address]) => ({
543
+ level: "warning",
544
+ text: clipConsoleText(
545
+ `DNS returned blocked 198.18.0.0/15 addresses, which may come from Clash or Mihomo fake-IP DNS. Inline the resource, add its host to fake-ip-filter, or switch DNS to redir-host. Affected host: ${host} (${address})`,
546
+ ),
547
+ }));
548
+
549
+ return { openPage, fakeIpNote };
550
});
551
552
const scratchDirectory = Effect.gen(function* () {
@@ -569,7 +582,12 @@ export const captureHtmlScreenshot = Effect.fn("headlessChrome.captureHtmlScreen
582
const contentHeight = yield* page.load(pageBody(input.html), input.urlFragment);
583
const capturedHeight = Math.max(1, Math.min(contentHeight, MAX_CAPTURE_HEIGHT));
584
const png = yield* page.screenshot(capturedHeight);
572
- return { png, contentHeight, capturedHeight, consoleMessages: page.consoleMessages() };
585
+ return {
586
+ png,
587
+ contentHeight,
588
+ capturedHeight,
589
+ consoleMessages: [...page.consoleMessages(), ...browser.fakeIpNote()],
590
+ };
591
},
592
Effect.scoped,
593
Effect.timeoutOrElse({
apps/server/src/htmlRender/publicProxy.test.ts
+34
-3
@@ -2,6 +2,8 @@
2
import { describe, expect, it } from "@effect/vitest";
3
import { vi } from "vite-plus/test";
4
import * as Effect from "effect/Effect";
5
+import type * as NodeDns from "node:dns";
6
+import * as NodeDnsPromises from "node:dns/promises";
7
import * as NodeNet from "node:net";
8
import * as NodeOS from "node:os";
9
@@ -28,6 +30,23 @@ vi.mock("node:os", async (importOriginal) => {
30
};
31
});
32
33
+// Clash and Mihomo answer every name from 198.18.0.0/16 in fake-IP mode.
34
+const TEST_DNS: Record<string, ReadonlyArray<{ address: string; family: number }>> = {
35
+ "cdn.fake-ip.test": [{ address: "198.18.2.40", family: 4 }],
36
+ "mixed.fake-ip.test": [
37
+ { address: "93.184.215.14", family: 4 },
38
+ { address: "198.18.2.41", family: 4 },
39
+ ],
40
+};
41
+vi.mock("node:dns/promises", async (importOriginal) => {
42
+ const actual = await importOriginal<typeof NodeDnsPromises>();
43
+ return {
44
+ ...actual,
45
+ lookup: (host: string, options: NodeDns.LookupOptions) =>
46
+ TEST_DNS[host] ? Promise.resolve(TEST_DNS[host]) : actual.lookup(host, options),
47
+ };
48
+});
49
+
50
const connectThrough = (proxyPort: number, target: Buffer, version = 5) =>
51
Effect.callback<{ readonly code: number; readonly socket: NodeNet.Socket }>((resume) => {
52
const socket = NodeNet.connect(proxyPort, "127.0.0.1", () => {
@@ -82,7 +101,7 @@ const domainTarget = (host: string, port: number) => {
101
describe("publicProxy", () => {
102
it.effect("refuses loopback and private targets, by address or by name", () =>
103
Effect.gen(function* () {
85
- const port = yield* publicProxy;
104
+ const { port } = yield* publicProxy;
105
for (const target of [
106
ipv4Target("127.0.0.1", 80),
107
ipv4Target("10.1.2.3", 80),
@@ -105,9 +124,21 @@ describe("publicProxy", () => {
124
}).pipe(Effect.scoped),
125
);
126
127
+ it.effect("refuses fake-IP names and records hosts whose every address is fake", () =>
128
+ Effect.gen(function* () {
129
+ const { port, fakeIpHosts } = yield* publicProxy;
130
+ for (const host of ["cdn.fake-ip.test", "mixed.fake-ip.test"]) {
131
+ const { code, socket } = yield* connectThrough(port, domainTarget(host, 443));
132
+ socket.destroy();
133
+ expect(code).toBe(2);
134
+ }
135
+ expect([...fakeIpHosts]).toEqual([["cdn.fake-ip.test", "198.18.2.40"]]);
136
+ }).pipe(Effect.scoped),
137
+ );
138
+
139
it.effect("refuses every address this machine holds, even a public one", () =>
140
Effect.gen(function* () {
110
- const port = yield* publicProxy;
141
+ const { port } = yield* publicProxy;
142
const own = Object.values(NodeOS.networkInterfaces())
143
.flatMap((entries) => entries ?? [])
144
.filter((entry) => !entry.internal && !entry.address.startsWith("fe80"));
@@ -132,7 +163,7 @@ describe("publicProxy", () => {
163
Effect.gen(function* () {
164
const socket = yield* Effect.scoped(
165
Effect.gen(function* () {
135
- const port = yield* publicProxy;
166
+ const { port } = yield* publicProxy;
167
return yield* Effect.callback<NodeNet.Socket>((resume) => {
168
const client = NodeNet.connect(port, "127.0.0.1", () => {
169
client.write(Buffer.from([5, 1, 0]));
apps/server/src/htmlRender/publicProxy.ts
+25
-7
@@ -31,6 +31,11 @@ for (const [network, prefix] of [
31
LOCAL_ADDRESSES.addSubnet(network, prefix, "ipv6");
32
}
33
34
+// Clash and Mihomo fake-IP DNS answers from here, inside the blocked 198.18.0.0/15.
35
+const FAKE_IP = new NodeNet.BlockList();
36
+FAKE_IP.addSubnet("198.18.0.0", 15, "ipv4");
37
+const MAX_FAKE_IP_HOSTS = 3;
38
+
39
const NAT64 = new NodeNet.BlockList();
40
NAT64.addSubnet("64:ff9b::", 96, "ipv6");
41
const SIX_TO_FOUR = new NodeNet.BlockList();
@@ -77,13 +82,20 @@ const isLocal = (address: string, family: number): boolean => {
82
};
83
84
// Connect only to checked addresses to prevent DNS rebinding.
80
-const publicAddresses = async (host: string) => {
85
+const publicAddresses = async (host: string, fakeIpHosts: Map<string, string>) => {
86
const addresses = NodeNet.isIP(host)
87
? [{ address: host, family: NodeNet.isIP(host) }]
88
: await NodeDnsPromises.lookup(host, { all: true, verbatim: true }).catch(() => []);
89
if (addresses.length === 0) return undefined;
90
const local = addresses.some(({ address, family }) => isLocal(address, family));
86
- return local ? undefined : addresses;
91
+ if (!local) return addresses;
92
+ const fake =
93
+ !NodeNet.isIP(host) &&
94
+ addresses.every(({ address, family }) => family === 4 && FAKE_IP.check(address, "ipv4"));
95
+ if (fake && fakeIpHosts.size < MAX_FAKE_IP_HOSTS && !fakeIpHosts.has(host)) {
96
+ fakeIpHosts.set(host, addresses[0]!.address);
97
+ }
98
+ return undefined;
99
};
100
101
// SOCKS5 (RFC 1928) replies: success, refused by rule, host unreachable, command unsupported.
@@ -116,10 +128,15 @@ const readRequest = (data: Buffer) => {
128
/** Covers requests Chrome's Local Network Access misses, including speculation prefetches. */
129
export const publicProxy = Effect.acquireRelease(
130
Effect.callback<
119
- { readonly server: NodeNet.Server; readonly sockets: Set<NodeNet.Socket> },
131
+ {
132
+ readonly server: NodeNet.Server;
133
+ readonly sockets: Set<NodeNet.Socket>;
134
+ readonly fakeIpHosts: ReadonlyMap<string, string>;
135
+ },
136
Error
137
>((resume) => {
138
const sockets = new Set<NodeNet.Socket>();
139
+ const fakeIpHosts = new Map<string, string>();
140
const track = (socket: NodeNet.Socket) => {
141
sockets.add(socket);
142
socket.on("close", () => sockets.delete(socket));
@@ -155,7 +172,7 @@ export const publicProxy = Effect.acquireRelease(
172
early.push(chunk);
173
};
174
client.on("data", holdEarly);
158
- void publicAddresses(request.host).then((addresses) => {
175
+ void publicAddresses(request.host, fakeIpHosts).then((addresses) => {
176
if (client.destroyed) return;
177
client.off("data", holdEarly);
178
if (addresses === undefined) return refuse(client, 2);
@@ -190,7 +207,7 @@ export const publicProxy = Effect.acquireRelease(
207
});
208
server.listen(0, "127.0.0.1", () => {
209
listening = true;
193
- resume(Effect.succeed({ server, sockets }));
210
+ resume(Effect.succeed({ server, sockets, fakeIpHosts }));
211
});
212
}),
213
({ server, sockets }) =>
@@ -199,8 +216,9 @@ export const publicProxy = Effect.acquireRelease(
216
server.close(() => resume(Effect.void));
217
}),
218
).pipe(
202
- Effect.map(({ server }) => {
219
+ Effect.map(({ server, fakeIpHosts }) => {
220
const address = server.address();
204
- return typeof address === "object" && address !== null ? address.port : 0;
221
+ const port = typeof address === "object" && address !== null ? address.port : 0;
222
+ return { port, fakeIpHosts };
223
}),
224
);
docs/user/html-renders.md
+2
@@ -8,6 +8,8 @@ Agents can place local images in a page by file path. T3 Code embeds them when t
8
9
Before publishing, agents check their work with screenshots from a small headless browser that T3 Code keeps for itself; it never uses a browser you installed. The first preview on a machine downloads it once (about 120 MB) into T3 Code's data folder, so that preview can take a minute. Browser tabs on a remote environment use the same browser, so whichever comes first downloads it. Some Linux hosts need [setup](remote-access.md#browser-host-setup) before it can start. Pages publish without it.
10
11
+Previews can load public resources such as CDN scripts, but nothing on your local network. The machine running the environment looks up each name, and previews block names that resolve to private or reserved addresses. Clash or Mihomo in fake-IP DNS mode can return these addresses, so external resources can fail there. The preview's console messages can identify affected hostnames. Inline the resource, add its host to `fake-ip-filter`, or switch that machine's proxy DNS to `redir-host`.
12
+
13
## MCP apps
14
15
Some MCP servers return an interactive app with their tool results, following the [MCP Apps](https://github.com/modelcontextprotocol/ext-apps) standard. When an agent calls one of those tools, the app appears in the thread in place of the tool call, on web, desktop, and mobile. Codex and Claude support this today, for any MCP server you have configured for them. Claude needs Claude Code 2.1.301 or newer; older versions and other providers show these calls as ordinary tool calls.