The best way to control Claude Code, Codex and more from any computer or phone
fix(ssh): desktop SSH reaches hosts with a one-time code through a signed-in ControlMaster (#30616)
Julius Marminge committed
Nov 19, 2026 at 12:43 UTC
f8d7f4891385cdf178271a1fd0dc8c5842b483a6
4 files changed
+203
-19
docs/user/remote-access.md
+12
@@ -259,6 +259,18 @@ check with:
259
ssh user@example.com 'sh -lc "command -v claude codex"'
260
```
261
262
+T3 Code cannot answer a second sign-in prompt such as a Duo code. On macOS and
263
+Linux it can reuse a connection you signed in to in a terminal instead: turn on
264
+connection sharing for the host in `~/.ssh/config`, run `ssh <alias>`, then
265
+connect. When that connection closes, sign in again in a terminal and retry.
266
+
267
+```sshconfig
268
+Host <alias>
269
+ ControlMaster auto
270
+ ControlPath ~/.ssh/cm-%C
271
+ ControlPersist 8h
272
+```
273
+
274
If SSH reconnecting fails after an app update, retry the launch once. Removing
275
the connection stops a server that T3 Code launched; a server that was already
276
running is left alone.
packages/ssh/src/command.ts
+35
-1
@@ -43,7 +43,7 @@ export interface RunSshCommandOptions extends SshAuthOptions {
43
readonly keepErrorOutputTail?: boolean;
44
}
45
46
-export function parseSshResolveOutput(alias: string, stdout: string): DesktopSshEnvironmentTarget {
46
+function parseSshConfigOutput(stdout: string): Map<string, string> {
47
const values = new Map<string, string>();
48
for (const line of stdout.split(/\r?\n/u)) {
49
const trimmed = line.trim();
@@ -56,6 +56,11 @@ export function parseSshResolveOutput(alias: string, stdout: string): DesktopSsh
56
}
57
values.set(key, rest.join(" ").trim());
58
}
59
+ return values;
60
+}
61
+
62
+export function parseSshResolveOutput(alias: string, stdout: string): DesktopSshEnvironmentTarget {
63
+ const values = parseSshConfigOutput(stdout);
64
65
const hostname = values.get("hostname")?.trim() || alias;
66
const username = values.get("user")?.trim() || null;
@@ -123,6 +128,12 @@ export function baseSshArgs(
128
];
129
}
130
131
+// `-F none` keeps the user's configured forwards out of T3's requests, and ProxyCommand=false
132
+// fails closed instead of dialing the host directly once the master is gone.
133
+export function controlMasterArgs(controlPath: string): string[] {
134
+ return ["-F", "none", "-o", `ControlPath=${controlPath}`, "-o", "ProxyCommand=false"];
135
+}
136
+
137
export function getLastNonEmptyOutputLine(stdout: string): string | null {
138
return (
139
stdout
@@ -442,3 +453,26 @@ export const resolveSshTarget = Effect.fn("ssh/command.resolveSshTarget")(functi
453
),
454
);
455
});
456
+
457
+/** The control path of the user's signed-in ControlMaster for `target`, or null when none is live. */
458
+export const findLiveControlPath = Effect.fn("ssh/command.findLiveControlPath")(function* (
459
+ target: DesktopSshEnvironmentTarget,
460
+): Effect.fn.Return<
461
+ string | null,
462
+ never,
463
+ ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path
464
+> {
465
+ const resolved = yield* runSshCommand(target, { preHostArgs: ["-G"] }).pipe(Effect.option);
466
+ const controlPath = Option.isSome(resolved)
467
+ ? parseSshConfigOutput(resolved.value.stdout).get("controlpath")
468
+ : undefined;
469
+ if (controlPath === undefined || controlPath === "none") {
470
+ return null;
471
+ }
472
+ return yield* runSshCommand(target, {
473
+ preHostArgs: [...controlMasterArgs(controlPath), "-O", "check"],
474
+ }).pipe(
475
+ Effect.as(controlPath),
476
+ Effect.orElseSucceed(() => null),
477
+ );
478
+});
packages/ssh/src/tunnel.test.ts
+77
@@ -1187,6 +1187,83 @@ describe("ssh tunnel scripts", () => {
1187
}),
1188
);
1189
1190
+ it.effect.each([
1191
+ { name: "rides a live ControlMaster", masterLive: true },
1192
+ { name: "keeps the auth failure without a live ControlMaster", masterLive: false },
1193
+ ])("when the tunnel cannot sign in again, $name", ({ masterLive }) =>
1194
+ Effect.gen(function* () {
1195
+ const denied = "julius@devbox: Permission denied (publickey,keyboard-interactive).\n";
1196
+ const openedForwards: Array<string | undefined> = [];
1197
+ const cancelledForwards: Array<string | undefined> = [];
1198
+ const spawner = ChildProcessSpawner.make((command) =>
1199
+ Effect.sync(() => {
1200
+ const args = commandArgs(command);
1201
+ const forward = args.includes("-L") ? args[args.indexOf("-L") + 1] : undefined;
1202
+ const muxCommand = args.includes("-O") ? args[args.indexOf("-O") + 1] : undefined;
1203
+ const failed = (stderr: string) => ({
1204
+ ...makeSuccessfulProcess(""),
1205
+ exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(255)),
1206
+ stderr: Stream.make(new TextEncoder().encode(stderr)),
1207
+ });
1208
+ if (args.includes("-G")) {
1209
+ return makeSuccessfulProcess("hostname devbox\ncontrolpath /tmp/t3-cm\n");
1210
+ }
1211
+ if (muxCommand === "check") {
1212
+ return masterLive
1213
+ ? makeSuccessfulProcess("")
1214
+ : failed("Control socket connect: ENOENT\n");
1215
+ }
1216
+ if (muxCommand === "cancel") {
1217
+ cancelledForwards.push(forward);
1218
+ return makeSuccessfulProcess("");
1219
+ }
1220
+ if (forward !== undefined) {
1221
+ // Only the signed-in master can pass the host's one-time-code prompt.
1222
+ if (!masterLive || args.includes("ControlPath=none")) return failed(denied);
1223
+ openedForwards.push(forward);
1224
+ return muxCommand === "forward"
1225
+ ? makeSuccessfulProcess("")
1226
+ : makeRunningProcess(() => undefined);
1227
+ }
1228
+ return makeSuccessfulProcess('{"remotePort":3773}\n');
1229
+ }),
1230
+ );
1231
+ const layer = Layer.mergeAll(
1232
+ NodeServices.layer,
1233
+ NodeCrypto.layer,
1234
+ Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, spawner),
1235
+ Layer.succeed(
1236
+ HttpClient.HttpClient,
1237
+ HttpClient.make((request) =>
1238
+ openedForwards.length > 0 ? testHttpClient.execute(request) : Effect.never,
1239
+ ),
1240
+ ),
1241
+ Layer.succeed(NetService.NetService, testNetService),
1242
+ SshAuth.SshPasswordPrompt.disabledLayer,
1243
+ SshTunnel.SshEnvironmentManager.layer({ resolveCliRunner: Effect.succeed(ARCHIVE) }),
1244
+ );
1245
+ const target = { alias: "devbox", hostname: "devbox", username: null, port: null };
1246
+ yield* Effect.gen(function* () {
1247
+ const manager = yield* SshTunnel.SshEnvironmentManager;
1248
+ const result = yield* Effect.result(manager.ensureEnvironment(target));
1249
+ if (!masterLive) {
1250
+ assert.isTrue(Result.isFailure(result));
1251
+ if (Result.isFailure(result)) {
1252
+ assert.instanceOf(result.failure, SshCommandError);
1253
+ assert.include(result.failure.message, "Permission denied");
1254
+ }
1255
+ assert.deepEqual(openedForwards, []);
1256
+ return;
1257
+ }
1258
+ assert.equal(Result.isFailure(result) ? result.failure.message : "connected", "connected");
1259
+ assert.lengthOf(openedForwards, 1);
1260
+ yield* manager.disconnectEnvironment(target);
1261
+ // The master keeps a forward after the client that asked for it exits.
1262
+ assert.deepEqual(cancelledForwards, openedForwards);
1263
+ }).pipe(Effect.provide(layer), Effect.scoped);
1264
+ }),
1265
+ );
1266
+
1267
it.live("concurrent launches on one remote home record the server that owns it", () =>
1268
// The second row's server never publishes server-runtime.json.
1269
Effect.forEach([1_500, null, "wrapper"] as const, (variant) =>
packages/ssh/src/tunnel.ts
+79
-18
@@ -32,6 +32,8 @@ import * as SshAuth from "./auth.ts";
32
import {
33
baseSshArgs,
34
buildSshHostSpecEffect,
35
+ controlMasterArgs,
36
+ findLiveControlPath,
37
getLastNonEmptyOutputLine,
38
remoteStateKey,
39
resolveSshCommand,
@@ -1471,6 +1473,8 @@ const startSshTunnel = Effect.fn("ssh/tunnel.startSshTunnel")(function* (input:
1473
readonly httpBaseUrl: string;
1474
readonly wsBaseUrl: string;
1475
readonly authOptions: SshAuth.SshAuthOptions;
1476
+ /** Forward through this live ControlMaster instead of signing in again. */
1477
+ readonly controlPath: string | null;
1478
readonly remoteServerKind: "external" | "managed" | null;
1479
readonly scope: Scope.Closeable;
1480
}): Effect.fn.Return<
@@ -1503,7 +1507,7 @@ const startSshTunnel = Effect.fn("ssh/tunnel.startSshTunnel")(function* (input:
1507
}),
1508
),
1509
);
1506
- const args = [
1510
+ const directArgs = [
1511
...baseSshArgs(input.resolvedTarget, {
1512
batchMode: input.authOptions.batchMode ?? "no",
1513
}),
@@ -1526,10 +1530,56 @@ const startSshTunnel = Effect.fn("ssh/tunnel.startSshTunnel")(function* (input:
1530
"--",
1531
hostSpec,
1532
];
1533
+ const { controlPath, scope } = input;
1534
+ // The master's own GatewayPorts would otherwise decide the bind address.
1535
+ const controlMasterForward = `127.0.0.1:${input.localPort}:127.0.0.1:${input.remotePort}`;
1536
+ const { args, stdin } =
1537
+ controlPath === null
1538
+ ? { args: directArgs, stdin: { stream: Stream.empty, endOnDone: true } }
1539
+ : {
1540
+ // A mux client with -N exits once the master takes the forward, so hold a session
1541
+ // open on stdin to keep a process whose exit means the tunnel is gone.
1542
+ args: [
1543
+ ...baseSshArgs(input.resolvedTarget, { batchMode: "yes" }),
1544
+ ...controlMasterArgs(controlPath),
1545
+ "-o",
1546
+ "ExitOnForwardFailure=yes",
1547
+ "-o",
1548
+ "ControlMaster=no",
1549
+ "-T",
1550
+ "-L",
1551
+ controlMasterForward,
1552
+ "--",
1553
+ hostSpec,
1554
+ "sh -c 'exec cat >/dev/null'",
1555
+ ],
1556
+ stdin: "pipe" as const,
1557
+ };
1558
const sshCommand = yield* resolveSshCommand;
1559
const tunnelCommand = [sshCommand, ...args];
1560
const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
1532
- const { scope } = input;
1561
+ if (controlPath !== null) {
1562
+ const fileSystemService = yield* FileSystem.FileSystem;
1563
+ const pathService = yield* Path.Path;
1564
+ // The master keeps a forward after the mux client that asked for it exits.
1565
+ yield* Scope.addFinalizer(
1566
+ scope,
1567
+ runSshCommand(input.resolvedTarget, {
1568
+ preHostArgs: [
1569
+ ...controlMasterArgs(controlPath),
1570
+ "-O",
1571
+ "cancel",
1572
+ "-L",
1573
+ controlMasterForward,
1574
+ ],
1575
+ }).pipe(
1576
+ Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
1577
+ Effect.provideService(FileSystem.FileSystem, fileSystemService),
1578
+ Effect.provideService(Path.Path, pathService),
1579
+ Effect.ignore,
1580
+ ),
1581
+ );
1582
+ }
1583
yield* Effect.logDebug("ssh.tunnel.spawn.start", {
1584
...sshTargetLogFields(input.resolvedTarget),
1585
command: tunnelCommand,
@@ -1543,10 +1593,7 @@ const startSshTunnel = Effect.fn("ssh/tunnel.startSshTunnel")(function* (input:
1593
ChildProcess.make(sshCommand, args, {
1594
env: childEnvironment,
1595
extendEnv: true,
1546
- stdin: {
1547
- stream: Stream.empty,
1548
- endOnDone: true,
1549
- },
1596
+ stdin,
1597
}),
1598
)
1599
.pipe(
@@ -1908,18 +1955,32 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
1955
const tunnelEntry = yield* runWithSshAuth({
1956
key: input.key,
1957
target: input.resolvedTarget,
1911
- operation: (authOptions) =>
1912
- startSshTunnel({
1913
- key: input.key,
1914
- resolvedTarget: input.resolvedTarget,
1915
- remotePort,
1916
- localPort,
1917
- httpBaseUrl,
1918
- wsBaseUrl,
1919
- authOptions,
1920
- remoteServerKind: remoteLaunch.remoteServerKind,
1921
- scope: entryScope,
1922
- }),
1958
+ operation: (authOptions) => {
1959
+ const start = (controlPath: string | null) =>
1960
+ startSshTunnel({
1961
+ key: input.key,
1962
+ resolvedTarget: input.resolvedTarget,
1963
+ remotePort,
1964
+ localPort,
1965
+ httpBaseUrl,
1966
+ wsBaseUrl,
1967
+ authOptions,
1968
+ controlPath,
1969
+ remoteServerKind: remoteLaunch.remoteServerKind,
1970
+ scope: entryScope,
1971
+ });
1972
+ // A fresh login cannot answer a second factor such as Duo, but the user's signed-in
1973
+ // ControlMaster already has. Without one, the auth failure goes on to the password prompt.
1974
+ return start(null).pipe(
1975
+ Effect.catchIf(SshAuth.isSshAuthFailure, (error) =>
1976
+ findLiveControlPath(input.resolvedTarget).pipe(
1977
+ Effect.flatMap((controlPath) =>
1978
+ controlPath === null ? Effect.fail(error) : start(controlPath),
1979
+ ),
1980
+ ),
1981
+ ),
1982
+ );
1983
+ },
1984
}).pipe(
1985
Effect.onExit((exit) =>
1986
Exit.isSuccess(exit) ? Effect.void : Scope.close(entryScope, Exit.void).pipe(Effect.ignore),