Skip to content

Commit c78712e

Browse files
fix(server): clarify browser setup when running as root (#22892)
Co-authored-by: maria-rcks <[email protected]>
1 parent 503bcaa commit c78712e

4 files changed

Lines changed: 66 additions & 8 deletions

File tree

‎apps/server/src/mcp/PreviewAutomationBroker.test.ts‎

Lines changed: 19 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ import * as Fiber from "effect/Fiber";
1919
import * as Result from "effect/Result";
2020
import * as Stream from "effect/Stream";
2121

22+
import { PreviewBrowserRootError } from "../preview/PreviewBrowserHost.ts";
2223
import * as PreviewAutomationBroker from "./PreviewAutomationBroker.ts";
2324

2425
const makeBroker = PreviewAutomationBroker.make.pipe(Effect.provide(NodeServices.layer));
@@ -288,9 +289,22 @@ it.effect("announces a live replacement stream before delivering requests", () =
288289
);
289290

290291
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 }) =>
294308
Effect.scoped(
295309
Effect.gen(function* () {
296310
const broker = yield* makeBroker;
@@ -303,7 +317,7 @@ it.effect.each([
303317
ok: false,
304318
error: {
305319
_tag: "PreviewAutomationExecutionError",
306-
message: "page.goto: net::ERR_CONNECTION_REFUSED at http://localhost:4719/",
320+
message,
307321
},
308322
}),
309323
).pipe(Effect.forkScoped);
@@ -312,7 +326,7 @@ it.effect.each([
312326
.invoke<void>({ scope, operation: "open", input: {} })
313327
.pipe(Effect.flip);
314328
expect(error._tag).toBe("PreviewAutomationExecutionError");
315-
expect(error.message.includes("ERR_CONNECTION_REFUSED")).toBe(shown);
329+
expect(error.message.includes(message)).toBe(shown);
316330
}),
317331
),
318332
);

‎apps/server/src/preview/PreviewBrowserHost.test.ts‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,36 @@ const diagnose = (input: {
7272
};
7373

7474
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+
75105
it.effect("names every library the loader cannot find", () =>
76106
Effect.gen(function* () {
77107
const { error } = yield* diagnose({

‎apps/server/src/preview/PreviewBrowserHost.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ export class PreviewBrowserRootError extends Schema.TaggedError<PreviewBrowserRo
7373
{},
7474
) {
7575
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.";
7777
}
7878
}
7979

‎docs/user/remote-access.md‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -259,8 +259,22 @@ any missing libraries and system fonts with apt; pages that load without text
259259
can mean the host has no fonts. It is safe to run again. Without `sudo`, it only
260260
reports what it would change.
261261

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.
264278

265279
## Connect an outside agent
266280

0 commit comments

Comments
 (0)