@devries-cameron20 / t3code Mirror · read-only / commits / c78712e84b
Fork 0

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