Skip to content

The open-source app everyone uses to manage agents at work

Sanitize remote execution envs at the boundary (#5325)

Devin Foleyf6bad8f6bf95
diff --git a/packages/adapter-utils/src/execution-target-sandbox.test.ts b/packages/adapter-utils/src/execution-target-sandbox.test.ts
index e0ebb37cc5..91bfd57d0d 100644
--- a/packages/adapter-utils/src/execution-target-sandbox.test.ts
+++ b/packages/adapter-utils/src/execution-target-sandbox.test.ts
@@ -19,6 +19,7 @@ describe("sandbox adapter execution targets", () => {
const cleanupDirs: string[] = [];
afterEach(async () => {
+ vi.unstubAllEnvs();
while (cleanupDirs.length > 0) {
const dir = cleanupDirs.pop();
if (!dir) continue;
@@ -141,6 +142,92 @@ describe("sandbox adapter execution targets", () => {
}));
});
+ it("strips inherited host identity env before sandbox execution", async () => {
+ vi.stubEnv("PATH", "/host/bin:/usr/bin");
+ vi.stubEnv("HOME", "/Users/local");
+ vi.stubEnv("TMPDIR", "/var/folders/local/T");
+
+ const runner = {
+ execute: vi.fn(async () => ({
+ exitCode: 0,
+ signal: null,
+ timedOut: false,
+ stdout: "ok\n",
+ stderr: "",
+ pid: null,
+ startedAt: new Date().toISOString(),
+ })),
+ };
+ const target: AdapterSandboxExecutionTarget = {
+ kind: "remote",
+ transport: "sandbox",
+ remoteCwd: "/workspace",
+ runner,
+ };
+
+ await runAdapterExecutionTargetProcess("run-1b", target, "agent-cli", ["--json"], {
+ cwd: "/local/workspace",
+ env: {
+ PATH: "/host/bin:/usr/bin",
+ HOME: "/Users/local",
+ TMPDIR: "/var/folders/local/T",
+ SAFE_VALUE: "visible",
+ },
+ timeoutSec: 5,
+ graceSec: 1,
+ onLog: async () => {},
+ });
+
+ expect(runner.execute).toHaveBeenCalledWith(expect.objectContaining({
+ env: {
+ SAFE_VALUE: "visible",
+ },
+ }));
+ });
+
+ it("preserves explicit remote identity env overrides for sandbox execution", async () => {
+ vi.stubEnv("PATH", "/host/bin:/usr/bin");
+ vi.stubEnv("HOME", "/Users/local");
+
+ const runner = {
+ execute: vi.fn(async () => ({
+ exitCode: 0,
+ signal: null,
+ timedOut: false,
+ stdout: "ok\n",
+ stderr: "",
+ pid: null,
+ startedAt: new Date().toISOString(),
+ })),
+ };
+ const target: AdapterSandboxExecutionTarget = {
+ kind: "remote",
+ transport: "sandbox",
+ remoteCwd: "/workspace",
+ runner,
+ };
+
+ await runAdapterExecutionTargetProcess("run-1c", target, "agent-cli", ["--json"], {
+ cwd: "/local/workspace",
+ env: {
+ PATH: "/custom/remote/bin:/usr/bin",
+ HOME: "/home/sandbox",
+ SAFE_VALUE: "visible",
+ },
+ timeoutSec: 5,
+ graceSec: 1,
+ onLog: async () => {},
+ });
+
+ expect(runner.execute).toHaveBeenCalledWith(expect.objectContaining({
+ env: {
+ PATH: "/custom/remote/bin:/usr/bin",
+ HOME: "/home/sandbox",
+ SAFE_VALUE: "visible",
+ },
+ }));
+ });
+
it("treats SSH targets as bridge-only", () => {
const target = {
kind: "remote" as const,
diff --git a/packages/adapter-utils/src/execution-target.test.ts b/packages/adapter-utils/src/execution-target.test.ts
index 71bcc34499..22b04ab8cb 100644
--- a/packages/adapter-utils/src/execution-target.test.ts
+++ b/packages/adapter-utils/src/execution-target.test.ts
@@ -1,15 +1,18 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import * as ssh from "./ssh.js";
+import * as serverUtils from "./server-utils.js";
import {
adapterExecutionTargetUsesManagedHome,
ensureAdapterExecutionTargetRuntimeCommandInstalled,
resolveAdapterExecutionTargetCwd,
+ runAdapterExecutionTargetProcess,
runAdapterExecutionTargetShellCommand,
} from "./execution-target.js";
describe("runAdapterExecutionTargetShellCommand", () => {
afterEach(() => {
vi.restoreAllMocks();
+ vi.unstubAllEnvs();
});
it("quotes remote shell commands with the shared SSH quoting helper", async () => {
@@ -42,13 +45,65 @@ describe("runAdapterExecutionTargetShellCommand", () => {
},
);
+ // runSshCommand owns profile sourcing and the outer `sh -lc` wrapper —
+ // the caller passes the raw command string. Wrapping it here would
+ // double-nest the login shell and re-source profiles after the explicit
+ // env override, silently undoing identity-var preservation.
expect(runSshCommandSpy).toHaveBeenCalledWith(
expect.objectContaining({
host: "ssh.example.test",
username: "ssh-user",
}),
- `sh -lc ${ssh.shellQuote(`printf '%s\\n' "$HOME" && echo "it's ok"`)}`,
+ `printf '%s\\n' "$HOME" && echo "it's ok"`,
+ expect.any(Object),
+ );
+ });
+
+ it("sanitizes inherited host env before SSH shell execution", async () => {
+ vi.stubEnv("PATH", "/host/bin:/usr/bin");
+ vi.stubEnv("HOME", "/Users/local");
+
+ const runSshCommandSpy = vi.spyOn(ssh, "runSshCommand").mockResolvedValue({
+ stdout: "",
+ stderr: "",
+ });
+
+ await runAdapterExecutionTargetShellCommand(
+ "run-1b",
+ {
+ kind: "remote",
+ transport: "ssh",
+ remoteCwd: "/srv/paperclip/workspace",
+ spec: {
+ host: "ssh.example.test",
+ port: 22,
+ username: "ssh-user",
+ remoteCwd: "/srv/paperclip/workspace",
+ remoteWorkspacePath: "/srv/paperclip/workspace",
+ privateKey: null,
+ knownHosts: null,
+ strictHostKeyChecking: true,
+ },
+ },
+ "env",
+ {
+ cwd: "/tmp/local",
+ env: {
+ PATH: "/host/bin:/usr/bin",
+ HOME: "/Users/local",
+ SAFE_VALUE: "visible",
+ },
+ },
+ );
+
+ expect(runSshCommandSpy).toHaveBeenCalledWith(
expect.any(Object),
+ expect.any(String),
+ expect.objectContaining({
+ env: {
+ SAFE_VALUE: "visible",
+ },
+ }),
);
});
@@ -162,6 +217,71 @@ describe("runAdapterExecutionTargetShellCommand", () => {
});
});
+describe("runAdapterExecutionTargetProcess", () => {
+ afterEach(() => {
+ vi.restoreAllMocks();
+ vi.unstubAllEnvs();
+ });
+
+ it("sanitizes inherited host env before SSH process execution", async () => {
+ vi.stubEnv("PATH", "/host/bin:/usr/bin");
+ vi.stubEnv("HOME", "/Users/local");
+
+ const runChildProcessSpy = vi.spyOn(serverUtils, "runChildProcess").mockResolvedValue({
+ exitCode: 0,
+ signal: null,
+ timedOut: false,
+ stdout: "",
+ stderr: "",
+ pid: null,
+ startedAt: new Date().toISOString(),
+ });
+
+ await runAdapterExecutionTargetProcess(
+ "run-ssh-process",
+ {
+ kind: "remote",
+ transport: "ssh",
+ remoteCwd: "/srv/paperclip/workspace",
+ spec: {
+ host: "ssh.example.test",
+ port: 22,
+ username: "ssh-user",
+ remoteCwd: "/srv/paperclip/workspace",
+ remoteWorkspacePath: "/srv/paperclip/workspace",
+ privateKey: null,
+ knownHosts: null,
+ strictHostKeyChecking: true,
+ },
+ },
+ "agent-cli",
+ ["--json"],
+ {
+ cwd: "/tmp/local",
+ env: {
+ PATH: "/host/bin:/usr/bin",
+ HOME: "/Users/local",
+ SAFE_VALUE: "visible",
+ },
+ timeoutSec: 5,
+ graceSec: 1,
+ onLog: async () => {},
+ },
+ );
+
+ expect(runChildProcessSpy).toHaveBeenCalledWith(
+ "run-ssh-process",
+ "agent-cli",
+ ["--json"],
+ expect.objectContaining({
+ env: {
+ SAFE_VALUE: "visible",
+ },
+ }),
+ );
+ });
+});
+
describe("ensureAdapterExecutionTargetRuntimeCommandInstalled", () => {
afterEach(() => {
vi.restoreAllMocks();
diff --git a/packages/adapter-utils/src/execution-target.ts b/packages/adapter-utils/src/execution-target.ts
index 563d1795e5..b51780d58f 100644
--- a/packages/adapter-utils/src/execution-target.ts
+++ b/packages/adapter-utils/src/execution-target.ts
@@ -26,6 +26,7 @@ import {
type RunProcessResult,
type TerminalResultCleanupOptions,
} from "./server-utils.js";
+import { sanitizeRemoteExecutionEnv } from "./remote-execution-env.js";
import { preferredShellForSandbox } from "./sandbox-shell.js";
export interface AdapterLocalExecutionTarget {
@@ -95,6 +96,8 @@ export interface AdapterExecutionTargetPaperclipBridgeHandle {
stop(): Promise<void>;
}
+export { sanitizeRemoteExecutionEnv } from "./remote-execution-env.js";
+
function parseObject(value: unknown): Record<string, unknown> {
return value && typeof value === "object" && !Array.isArray(value)
? (value as Record<string, unknown>)
@@ -340,11 +343,12 @@ export async function runAdapterExecutionTargetProcess(
): Promise<RunProcessResult> {
if (target?.kind === "remote" && target.transport === "sandbox") {
const runner = requireSandboxRunner(target);
+ const env = sanitizeRemoteExecutionEnv(options.env);
return await runner.execute({
command,
args,
cwd: target.remoteCwd,
- env: options.env,
+ env,
stdin: options.stdin,
timeoutMs: options.timeoutSec > 0 ? options.timeoutSec * 1000 : target.timeoutMs ?? undefined,
onLog: options.onLog,
@@ -354,9 +358,14 @@ export async function runAdapterExecutionTargetProcess(
});
}
+ const env =
+ target?.kind === "remote" && target.transport === "ssh"
+ ? sanitizeRemoteExecutionEnv(options.env)
+ : options.env;
+
return await runChildProcess(runId, command, args, {
cwd: options.cwd,
- env: options.env,
+ env,
stdin: options.stdin,
timeoutSec: options.timeoutSec,
graceSec: options.graceSec,
@@ -376,9 +385,16 @@ export async function runAdapterExecutionTargetShellCommand(
const onLog = options.onLog ?? (async () => {});
if (target?.kind === "remote") {
const startedAt = new Date().toISOString();
+ const env = sanitizeRemoteExecutionEnv(options.env);
if (target.transport === "ssh") {
try {
- const result = await runSshCommand(target.spec, `sh -lc ${shellQuote(command)}`, {
+ // Pass the raw command — `runSshCommand` owns profile sourcing and
+ // the outer `sh -lc` wrapper. Wrapping again here would nest a second
+ // `sh -lc` after the explicit `env KEY=VAL` overrides, re-sourcing
+ // login profiles AFTER the override and silently undoing any
+ // identity var (NVM_DIR / PATH / etc.) that a profile re-exports.
+ const result = await runSshCommand(target.spec, command, {
+ env,
timeoutMs: (options.timeoutSec ?? 15) * 1000,
});
if (result.stdout) await onLog("stdout", result.stdout);
@@ -435,7 +451,7 @@ export async function runAdapterExecutionTargetShellCommand(
command: shellCommand,
args: ["-lc", command],
cwd: target.remoteCwd,
- env: options.env,
+ env,
timeoutMs: (options.timeoutSec ?? 15) * 1000,
onLog,
});
diff --git a/packages/adapter-utils/src/remote-execution-env.ts b/packages/adapter-utils/src/remote-execution-env.ts
new file mode 100644
index 0000000000..9bc900228c
--- /dev/null
+++ b/packages/adapter-utils/src/remote-execution-env.ts
@@ -0,0 +1,49 @@
+const REMOTE_EXECUTION_ENV_IDENTITY_KEYS = new Set([
+ "PATH",
+ "HOME",
+ "PWD",
+ "SHELL",
+ "USER",
+ "LOGNAME",
+ "NVM_DIR",
+ "TMPDIR",
+ "TMP",
+ "TEMP",
+ "XDG_CONFIG_HOME",
+ "XDG_CACHE_HOME",
+ "XDG_DATA_HOME",
+ "XDG_STATE_HOME",
+ "XDG_RUNTIME_DIR",
+]);
+
+function readEnvValueCaseInsensitive(env: NodeJS.ProcessEnv, key: string): string | undefined {
+ const direct = env[key];
+ if (typeof direct === "string") return direct;
+ const upper = key.toUpperCase();
+ for (const [candidateKey, candidateValue] of Object.entries(env)) {
+ if (candidateKey.toUpperCase() === upper && typeof candidateValue === "string") {
+ return candidateValue;
+ }
+ }
+ return undefined;
+}
+
+export function sanitizeRemoteExecutionEnv(
+ env: Record<string, string>,
+ inheritedEnv: NodeJS.ProcessEnv = process.env,
+): Record<string, string> {
+ const sanitized: Record<string, string> = {};
+ for (const [key, value] of Object.entries(env)) {
+ const normalizedKey = key.toUpperCase();
+ if (!REMOTE_EXECUTION_ENV_IDENTITY_KEYS.has(normalizedKey)) {
+ sanitized[key] = value;
+ continue;
+ }
+ const inheritedValue = readEnvValueCaseInsensitive(inheritedEnv, key);
+ if (typeof inheritedValue === "string" && inheritedValue === value) {
+ continue;
+ }
+ sanitized[key] = value;
+ }
+ return sanitized;
+}
diff --git a/packages/adapter-utils/src/server-utils.ts b/packages/adapter-utils/src/server-utils.ts
index 1a07f643f8..83420182b1 100644
--- a/packages/adapter-utils/src/server-utils.ts
+++ b/packages/adapter-utils/src/server-utils.ts
@@ -2,6 +2,7 @@ import { spawn, type ChildProcess } from "node:child_process";
import { createHash, randomUUID } from "node:crypto";
import { constants as fsConstants, promises as fs, type Dirent } from "node:fs";
import path from "node:path";
+import { sanitizeRemoteExecutionEnv } from "./remote-execution-env.js";
import { buildSshSpawnTarget, type SshRemoteExecutionSpec } from "./ssh.js";
import { redactCommandText } from "./command-redaction.js";
import type {
@@ -1039,54 +1040,11 @@ function quoteForCmd(arg: string) {
return /[\s"&<>|^()]/.test(escaped) ? `"${escaped}"` : escaped;
}
-const SSH_REMOTE_ENV_IDENTITY_KEYS = new Set([
- "PATH",
- "HOME",
- "PWD",
- "SHELL",
- "USER",
- "LOGNAME",
- "NVM_DIR",
- "TMPDIR",
- "TMP",
- "TEMP",
- "XDG_CONFIG_HOME",
- "XDG_CACHE_HOME",
- "XDG_DATA_HOME",
- "XDG_STATE_HOME",
- "XDG_RUNTIME_DIR",
-]);
-
-function readEnvValueCaseInsensitive(env: NodeJS.ProcessEnv, key: string): string | undefined {
- const direct = env[key];
- if (typeof direct === "string") return direct;
- const upper = key.toUpperCase();
- for (const [candidateKey, candidateValue] of Object.entries(env)) {
- if (candidateKey.toUpperCase() === upper && typeof candidateValue === "string") {
- return candidateValue;
- }
- }
- return undefined;
-}
-
export function sanitizeSshRemoteEnv(
env: Record<string, string>,
inheritedEnv: NodeJS.ProcessEnv = process.env,
): Record<string, string> {
- const sanitized: Record<string, string> = {};
- for (const [key, value] of Object.entries(env)) {
- const normalizedKey = key.toUpperCase();
- if (!SSH_REMOTE_ENV_IDENTITY_KEYS.has(normalizedKey)) {
- sanitized[key] = value;
- continue;
- }
- const inheritedValue = readEnvValueCaseInsensitive(inheritedEnv, key);
- if (typeof inheritedValue === "string" && inheritedValue === value) {
- continue;
- }
- sanitized[key] = value;
- }
- return sanitized;
+ return sanitizeRemoteExecutionEnv(env, inheritedEnv);
}
function resolveWindowsCmdShell(env: NodeJS.ProcessEnv): string {
@@ -1114,9 +1072,9 @@ async function resolveSpawnTarget(
spec: remote,
command,
args,
- env: sanitizeSshRemoteEnv(Object.fromEntries(
+ env: Object.fromEntries(
Object.entries(options.remoteEnv ?? {}).filter((entry): entry is [string, string] => typeof entry[1] === "string"),
- )),
+ ),
});
return {
command: sshResolved,
diff --git a/packages/adapter-utils/src/ssh.ts b/packages/adapter-utils/src/ssh.ts
index 39087b3e60..2b5dbbadb5 100644
--- a/packages/adapter-utils/src/ssh.ts
+++ b/packages/adapter-utils/src/ssh.ts
@@ -721,6 +721,7 @@ export async function runSshCommand(
config: SshConnectionConfig,
remoteCommand: string,
options: {
+ env?: Record<string, string>;
timeoutMs?: number;
maxBuffer?: number;
} = {},
@@ -730,12 +731,33 @@ export async function runSshCommand(
const auth = await createSshAuthArgs(config);
cleanup = auth.cleanup;
const sshArgs = [...auth.args];
+ const envEntries = Object.entries(options.env ?? {})
+ .filter((entry): entry is [string, string] => typeof entry[1] === "string");
+ for (const [key] of envEntries) {
+ if (!isValidShellEnvKey(key)) {
+ throw new Error(`Invalid SSH environment variable key: ${key}`);
+ }
+ }
+
+ // Mirror buildSshSpawnTarget: source login profiles first, then run
+ // `env KEY=VAL cmd` so user-supplied identity overrides win over anything
+ // a profile re-exports. Without this, a remote profile that resets HOME
+ // / NVM_DIR / etc. would silently undo the explicit env passed in here.
+ const envArgs = envEntries.map(([key, value]) => `${key}=${shellQuote(value)}`);
+ const remoteScript = [
+ 'if [ -f "$HOME/.profile" ]; then . "$HOME/.profile" >/dev/null 2>&1 || true; fi',
+ 'if [ -f "$HOME/.bash_profile" ]; then . "$HOME/.bash_profile" >/dev/null 2>&1 || true; fi',
+ 'if [ -f "$HOME/.zprofile" ]; then . "$HOME/.zprofile" >/dev/null 2>&1 || true; fi',
+ envArgs.length > 0
+ ? `exec env ${envArgs.join(" ")} sh -c ${shellQuote(remoteCommand)}`
+ : `exec sh -c ${shellQuote(remoteCommand)}`,
+ ].join(" && ");
sshArgs.push(
"-p",
String(config.port),
`${config.username}@${config.host}`,
- remoteCommand,
+ `sh -lc ${shellQuote(remoteScript)}`,
);
return await execFileText("ssh", sshArgs, {
diff --git a/packages/adapters/opencode-local/src/server/test.ts b/packages/adapters/opencode-local/src/server/test.ts
index a4758084a7..e0959d5f72 100644
--- a/packages/adapters/opencode-local/src/server/test.ts
+++ b/packages/adapters/opencode-local/src/server/test.ts
@@ -290,13 +290,6 @@ export async function testEnvironment(
if (variant) args.push("--variant", variant);
if (extraArgs.length > 0) args.push(...extraArgs);
- // For remote targets, do NOT spread the host process.env into the
- // probe env: it leaks macOS-only paths (HOME=/Users/..., host
- // XDG_CONFIG_HOME, TMPDIR, etc.) into the remote shell, which causes
- // opencode on the remote box to try to mkdir host paths like /Users.
- // Match the pattern used by claude_local / codex_local / gemini_local
- // probes: send only the user-configured adapter env across SSH.
- const probeEnv = targetIsRemote ? preparedRuntimeConfig.env : runtimeEnv;
try {
const probe = await runAdapterExecutionTargetProcess(
runId,
@@ -305,7 +298,7 @@ export async function testEnvironment(
args,
{
cwd,
- env: probeEnv,
+ env: runtimeEnv,
timeoutSec: 60,
graceSec: 5,
stdin: "Respond with hello.",
diff --git a/packages/adapters/pi-local/src/server/test.ts b/packages/adapters/pi-local/src/server/test.ts
index aef648ef54..782699ce7f 100644
--- a/packages/adapters/pi-local/src/server/test.ts
+++ b/packages/adapters/pi-local/src/server/test.ts
@@ -259,17 +259,6 @@ export async function testEnvironment(
args.push("--tools", "read");
if (extraArgs.length > 0) args.push(...extraArgs);
- // For remote targets, do NOT spread the host process.env into the probe
- // env: it leaks macOS-only PATH, HOME, TMPDIR, etc. into the remote shell.
- // In particular the Mac PATH overrides the nvm-sourced PATH that
- // buildSshSpawnTarget sets up, which on Linux SSH targets resolves `node`
- // to /usr/bin/node (Node 18) instead of nvm's Node 22, causing pi-tui to
- // crash with `Invalid regular expression flags` on its /v unicode regex.
- // Match the pattern used by claude_local / codex_local / gemini_local /
- // opencode_local probes: send only the user-configured adapter env across
- // SSH. Local probes still get the full runtimeEnv.
- const probeEnv = targetIsRemote ? normalizeEnv(env) : runtimeEnv;
-
try {
const probe = await runAdapterExecutionTargetProcess(
runId,
@@ -278,7 +267,7 @@ export async function testEnvironment(
args,
{
cwd,
- env: probeEnv,
+ env: runtimeEnv,
timeoutSec: 60,
graceSec: 5,
onLog: async () => {},