Skip to content

Commit 57fa0ab

Browse files
committed
fix(server): clarify browser setup when running as root
1 parent 448b8a9 commit 57fa0ab

3 files changed

Lines changed: 47 additions & 3 deletions

File tree

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

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

7575
describe("diagnoseLaunchFailure", () => {
76+
it.effect("explains how to restart a root server without Chrome's sandbox", () =>
77+
Effect.gen(function* () {
78+
const { error, commands } = yield* diagnose({
79+
platform: "linux",
80+
uid: 0,
81+
output: PreviewBrowserHost.NO_SANDBOX_SIGNATURE,
82+
ldd: "",
83+
});
84+
expect(error).toBeInstanceOf(PreviewBrowserHost.PreviewBrowserRootError);
85+
expect(error?.message).toContain("T3 server is running as root");
86+
expect(error?.message).toContain("T3 server's environment and restart the server");
87+
expect(error?.message).toContain("T3CODE_SERVER_BROWSER_SANDBOX=0 t3 serve");
88+
expect(error?.message).toContain("Environment=T3CODE_SERVER_BROWSER_SANDBOX=0");
89+
expect(error?.message).toContain("this disables Chrome's sandbox");
90+
expect(commands).toEqual([]);
91+
}),
92+
);
93+
94+
it.effect("keeps host setup guidance for a nonroot sandbox failure", () =>
95+
Effect.gen(function* () {
96+
const { error } = yield* diagnose({
97+
platform: "linux",
98+
output: PreviewBrowserHost.NO_SANDBOX_SIGNATURE,
99+
ldd: "",
100+
});
101+
expect(error).toBeInstanceOf(PreviewBrowserHost.PreviewBrowserSandboxError);
102+
expect(error?.message).toContain("Run `sudo t3 browser setup` on the host");
103+
}),
104+
);
105+
76106
it.effect("names every library the loader cannot find", () =>
77107
Effect.gen(function* () {
78108
const { error } = yield* diagnose({

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ export class PreviewBrowserRootError extends Schema.TaggedError<PreviewBrowserRo
7979
{},
8080
) {
8181
override get message(): string {
82-
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.";
82+
return "T3's browser could not start because the T3 server is running as root and Chrome's sandbox does not support root. Run the T3 server as a nonroot user to keep sandboxing enabled. If you need to run as root, set `T3CODE_SERVER_BROWSER_SANDBOX=0` in the T3 server's environment and restart the server; this disables Chrome's sandbox. For a manual launch, use `T3CODE_SERVER_BROWSER_SANDBOX=0 t3 serve`. For a systemd service, add `Environment=T3CODE_SERVER_BROWSER_SANDBOX=0` under `[Service]`, then reload systemd and restart the service. Running `t3 browser setup` does not fix this root restriction.";
8383
}
8484
}
8585

‎docs/user/remote-access.md‎

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

240-
The browser always runs in Chrome's sandbox. Where you cannot change the host,
241-
set `T3CODE_SERVER_BROWSER_SANDBOX=0` for the environment to run without it.
240+
The browser runs in Chrome's sandbox by default. Chrome cannot start that sandbox
241+
as root. If your T3 server runs as root, run it as a nonroot user to keep
242+
sandboxing enabled. `t3 browser setup` does not fix this root restriction.
243+
244+
If you need to run as root, or cannot enable the sandbox on your host, set
245+
`T3CODE_SERVER_BROWSER_SANDBOX=0` in the **T3 server's environment** and restart
246+
the server. This disables Chrome's sandbox. For a manual launch:
247+
248+
```sh
249+
T3CODE_SERVER_BROWSER_SANDBOX=0 t3 serve
250+
```
251+
252+
For a systemd service, add `Environment=T3CODE_SERVER_BROWSER_SANDBOX=0` under
253+
`[Service]` in its configuration, run `sudo systemctl daemon-reload`, then restart
254+
your T3 service. Setting the variable in an agent's terminal does not change the
255+
environment of an already running T3 server.
242256

243257
## Connect an outside agent
244258

0 commit comments

Comments
 (0)