The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 22, 12:00 UTC
fix(server): clarify browser setup when running as root (#22892)
Co-authored-by: maria-rcks <maria@kuuro.net>
Jaron Kramer committed
Oct 30, 2026 at 22:43 UTC
c78712e84bcda486b3518b995235004bf9654335
4 files changed
+66
-8
apps/server/src/mcp/PreviewAutomationBroker.test.ts
+19
-5
@@ -19,6 +19,7 @@ import * as Fiber from "effect/Fiber";
19
import * as Result from "effect/Result";
20
import * as Stream from "effect/Stream";
21
22
+import { PreviewBrowserRootError } from "../preview/PreviewBrowserHost.ts";
23
import * as PreviewAutomationBroker from "./PreviewAutomationBroker.ts";
24
25
const makeBroker = PreviewAutomationBroker.make.pipe(Effect.provide(NodeServices.layer));
@@ -288,9 +289,22 @@ it.effect("announces a live replacement stream before delivering requests", () =
289
);
290
291
it.effect.each([
291
- { clientId: SERVER_BROWSER_AUTOMATION_CLIENT_ID, shown: true },
292
- { clientId: "client-1", shown: false },
293
-])("tells the agent why its own server browser failed ($clientId)", ({ clientId, shown }) =>
292
+ {
293
+ clientId: SERVER_BROWSER_AUTOMATION_CLIENT_ID,
294
+ shown: true,
295
+ message: "page.goto: net::ERR_CONNECTION_REFUSED at http://localhost:4719/",
296
+ },
297
+ {
298
+ clientId: "client-1",
299
+ shown: false,
300
+ message: "page.goto: net::ERR_CONNECTION_REFUSED at http://localhost:4719/",
301
+ },
302
+ {
303
+ clientId: SERVER_BROWSER_AUTOMATION_CLIENT_ID,
304
+ shown: true,
305
+ message: new PreviewBrowserRootError().message,
306
+ },
307
+])("preserves server browser failure guidance ($clientId)", ({ clientId, shown, message }) =>
308
Effect.scoped(
309
Effect.gen(function* () {
310
const broker = yield* makeBroker;
@@ -303,7 +317,7 @@ it.effect.each([
317
ok: false,
318
error: {
319
_tag: "PreviewAutomationExecutionError",
306
- message: "page.goto: net::ERR_CONNECTION_REFUSED at http://localhost:4719/",
320
+ message,
321
},
322
}),
323
).pipe(Effect.forkScoped);
@@ -312,7 +326,7 @@ it.effect.each([
326
.invoke<void>({ scope, operation: "open", input: {} })
327
.pipe(Effect.flip);
328
expect(error._tag).toBe("PreviewAutomationExecutionError");
315
- expect(error.message.includes("ERR_CONNECTION_REFUSED")).toBe(shown);
329
+ expect(error.message.includes(message)).toBe(shown);
330
}),
331
),
332
);
apps/server/src/preview/PreviewBrowserHost.test.ts
+30
@@ -72,6 +72,36 @@ const diagnose = (input: {
72
};
73
74
describe("diagnoseLaunchFailure", () => {
75
+ it.effect("explains how to restart a root server without Chrome's sandbox", () =>
76
+ Effect.gen(function* () {
77
+ const { error, commands } = yield* diagnose({
78
+ platform: "linux",
79
+ uid: 0,
80
+ output: PreviewBrowserHost.NO_SANDBOX_SIGNATURE,
81
+ ldd: "",
82
+ });
83
+ expect(error).toBeInstanceOf(PreviewBrowserHost.PreviewBrowserRootError);
84
+ expect(error?.message).toContain("T3 server is running as root");
85
+ expect(error?.message).toContain("T3 server's environment and restart the server");
86
+ expect(error?.message).toContain("T3CODE_SERVER_BROWSER_SANDBOX=0 t3 serve");
87
+ expect(error?.message).toContain("Environment=T3CODE_SERVER_BROWSER_SANDBOX=0");
88
+ expect(error?.message).toContain("this disables Chrome's sandbox");
89
+ expect(commands).toEqual([]);
90
+ }),
91
+ );
92
+
93
+ it.effect("keeps host setup guidance for a nonroot sandbox failure", () =>
94
+ Effect.gen(function* () {
95
+ const { error } = yield* diagnose({
96
+ platform: "linux",
97
+ output: PreviewBrowserHost.NO_SANDBOX_SIGNATURE,
98
+ ldd: "",
99
+ });
100
+ expect(error).toBeInstanceOf(PreviewBrowserHost.PreviewBrowserSandboxError);
101
+ expect(error?.message).toContain("Run `sudo t3 browser setup` on the host");
102
+ }),
103
+ );
104
+
105
it.effect("names every library the loader cannot find", () =>
106
Effect.gen(function* () {
107
const { error } = yield* diagnose({
apps/server/src/preview/PreviewBrowserHost.ts
+1
-1
@@ -73,7 +73,7 @@ export class PreviewBrowserRootError extends Schema.TaggedError<PreviewBrowserRo
73
{},
74
) {
75
override get message(): string {
76
- return "Chrome will not start its sandbox as root, so T3's browser cannot run while the T3 server runs as root. Run the server as a nonroot user (for example `User=` in its systemd service), or set `T3CODE_SERVER_BROWSER_SANDBOX=0` to run the browser unsandboxed as root.";
76
+ return "T3 server is running as root; Chrome's sandbox cannot start. Run T3 as a nonroot user. Otherwise set `T3CODE_SERVER_BROWSER_SANDBOX=0` in the T3 server's environment and restart the server; this disables Chrome's sandbox. Manual: `T3CODE_SERVER_BROWSER_SANDBOX=0 t3 serve`. Systemd: add `Environment=T3CODE_SERVER_BROWSER_SANDBOX=0` under `[Service]`, reload systemd, then restart the service. `t3 browser setup` cannot fix root sandboxing.";
77
}
78
}
79
docs/user/remote-access.md
+16
-2
@@ -259,8 +259,22 @@ any missing libraries and system fonts with apt; pages that load without text
259
can mean the host has no fonts. It is safe to run again. Without `sudo`, it only
260
reports what it would change.
261
262
-The browser always runs in Chrome's sandbox. Where you cannot change the host,
263
-set `T3CODE_SERVER_BROWSER_SANDBOX=0` for the environment to run without it.
262
+The browser runs in Chrome's sandbox by default. Chrome cannot start that sandbox
263
+as root. If your T3 server runs as root, run it as a nonroot user to keep
264
+sandboxing enabled. `t3 browser setup` does not fix this root restriction.
265
+
266
+If you need to run as root, or cannot enable the sandbox on your host, set
267
+`T3CODE_SERVER_BROWSER_SANDBOX=0` in the **T3 server's environment** and restart
268
+the server. This disables Chrome's sandbox. For a manual launch:
269
+
270
+```sh
271
+T3CODE_SERVER_BROWSER_SANDBOX=0 t3 serve
272
+```
273
+
274
+For a systemd service, add `Environment=T3CODE_SERVER_BROWSER_SANDBOX=0` under
275
+`[Service]` in its configuration, run `sudo systemctl daemon-reload`, then restart
276
+your T3 service. Setting the variable in an agent's terminal does not change the
277
+environment of an already running T3 server.
278
279
## Connect an outside agent
280