Add SSH environment support (#4358)

## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - The environments subsystem already models execution environments, but before this branch there was no end-to-end SSH-backed runtime path for agents to actually run work against a remote box > - That meant agents could be configured around environment concepts without a reliable way to execute adapter sessions remotely, sync workspace state, and preserve run context across supported adapters > - We also need environment selection to participate in normal Paperclip control-plane behavior: agent defaults, project/issue selection, route validation, and environment probing > - Because this capability is still experimental, the UI surface should be easy to hide and easy to remove later without undoing the underlying implementation > - This pull request adds SSH environment execution support across the runtime, adapters, routes, schema, and tests, then puts the visible environment-management UI behind an experimental flag > - The benefit is that we can validate real SSH-backed agent execution now while keeping the user-facing controls safely gated until the feature is ready to come out of experimentation ## What Changed - Added SSH-backed execution target support in the shared adapter runtime, including remote workspace preparation, skill/runtime asset sync, remote session handling, and workspace restore behavior after runs. - Added SSH execution coverage for supported local adapters, plus remote execution tests across Claude, Codex, Cursor, Gemini, OpenCode, and Pi. - Added environment selection and environment-management backend support needed for SSH execution, including route/service work, validation, probing, and agent default environment persistence. - Added CLI support for SSH environment lab verification and updated related docs/tests. - Added the `enableEnvironments` experimental flag and gated the environment UI behind it on company settings, agent configuration, and project configuration surfaces. ## Verification - `pnpm exec vitest run packages/adapters/claude-local/src/server/execute.remote.test.ts packages/adapters/cursor-local/src/server/execute.remote.test.ts packages/adapters/gemini-local/src/server/execute.remote.test.ts packages/adapters/opencode-local/src/server/execute.remote.test.ts packages/adapters/pi-local/src/server/execute.remote.test.ts` - `pnpm exec vitest run server/src/__tests__/environment-routes.test.ts` - `pnpm exec vitest run server/src/__tests__/instance-settings-routes.test.ts` - `pnpm exec vitest run ui/src/lib/new-agent-hire-payload.test.ts ui/src/lib/new-agent-runtime-config.test.ts` - `pnpm -r typecheck` - `pnpm build` - Manual verification on a branch-local dev server: - enabled the experimental flag - created an SSH environment - created a Linux Claude agent using that environment - confirmed a run executed on the Linux box and synced workspace changes back ## Risks - Medium: this touches runtime execution flow across multiple adapters, so regressions would likely show up in remote session setup, workspace sync, or environment selection precedence. - The UI flag reduces exposure, but the underlying runtime and route changes are still substantial and rely on migration correctness. - The change set is broad across adapters, control-plane services, migrations, and UI gating, so review should pay close attention to environment-selection precedence and remote workspace lifecycle behavior. ## Model Used - OpenAI Codex via Paperclip's local Codex adapter, GPT-5-class coding model with tool use and code execution in the local repo workspace. The local adapter does not surface a more specific public model version string in this branch workflow. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge
2026-06-14 01:50:39 +09:00 · 2026-04-23 19:15:22 -07:00 · 2026-04-23 19:15:22 -07:00 · e4995bbb1c
commit e4995bbb1c
parent f98c348e2b
95 changed files with 10162 additions and 315 deletions
--- a/packages/adapter-utils/src/execution-target.test.ts
+++ b/packages/adapter-utils/src/execution-target.test.ts
@ -0,0 +1,161 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import * as ssh from "./ssh.js";
+import {
+  adapterExecutionTargetUsesManagedHome,
+  runAdapterExecutionTargetShellCommand,
+} from "./execution-target.js";
+
+describe("runAdapterExecutionTargetShellCommand", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("quotes remote shell commands with the shared SSH quoting helper", async () => {
+    const runSshCommandSpy = vi.spyOn(ssh, "runSshCommand").mockResolvedValue({
+      stdout: "",
+      stderr: "",
+    });
+
+    await runAdapterExecutionTargetShellCommand(
+      "run-1",
+      {
+        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,
+        },
+      },
+      `printf '%s\\n' "$HOME" && echo "it's ok"`,
+      {
+        cwd: "/tmp/local",
+        env: {},
+      },
+    );
+
+    expect(runSshCommandSpy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        host: "ssh.example.test",
+        username: "ssh-user",
+      }),
+      `sh -lc ${ssh.shellQuote(`printf '%s\\n' "$HOME" && echo "it's ok"`)}`,
+      expect.any(Object),
+    );
+  });
+
+  it("returns a timedOut result when the SSH shell command times out", async () => {
+    vi.spyOn(ssh, "runSshCommand").mockRejectedValue(Object.assign(new Error("timed out"), {
+      code: "ETIMEDOUT",
+      stdout: "partial stdout",
+      stderr: "partial stderr",
+      signal: "SIGTERM",
+    }));
+    const onLog = vi.fn(async () => {});
+
+    const result = await runAdapterExecutionTargetShellCommand(
+      "run-2",
+      {
+        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,
+        },
+      },
+      "sleep 10",
+      {
+        cwd: "/tmp/local",
+        env: {},
+        onLog,
+      },
+    );
+
+    expect(result).toMatchObject({
+      exitCode: null,
+      signal: "SIGTERM",
+      timedOut: true,
+      stdout: "partial stdout",
+      stderr: "partial stderr",
+    });
+    expect(onLog).toHaveBeenCalledWith("stdout", "partial stdout");
+    expect(onLog).toHaveBeenCalledWith("stderr", "partial stderr");
+  });
+
+  it("returns the SSH process exit code for non-zero remote command failures", async () => {
+    vi.spyOn(ssh, "runSshCommand").mockRejectedValue(Object.assign(new Error("non-zero exit"), {
+      code: 17,
+      stdout: "partial stdout",
+      stderr: "partial stderr",
+      signal: null,
+    }));
+    const onLog = vi.fn(async () => {});
+
+    const result = await runAdapterExecutionTargetShellCommand(
+      "run-3",
+      {
+        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,
+        },
+      },
+      "false",
+      {
+        cwd: "/tmp/local",
+        env: {},
+        onLog,
+      },
+    );
+
+    expect(result).toMatchObject({
+      exitCode: 17,
+      signal: null,
+      timedOut: false,
+      stdout: "partial stdout",
+      stderr: "partial stderr",
+    });
+    expect(onLog).toHaveBeenCalledWith("stdout", "partial stdout");
+    expect(onLog).toHaveBeenCalledWith("stderr", "partial stderr");
+  });
+
+  it("keeps managed homes disabled for both local and SSH targets", () => {
+    expect(adapterExecutionTargetUsesManagedHome(null)).toBe(false);
+    expect(adapterExecutionTargetUsesManagedHome({
+      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,
+      },
+    })).toBe(false);
+  });
+});
--- a/packages/adapter-utils/src/execution-target.ts
+++ b/packages/adapter-utils/src/execution-target.ts
@ -0,0 +1,399 @@
+import path from "node:path";
+import type { SshRemoteExecutionSpec } from "./ssh.js";
+import {
+  buildRemoteExecutionSessionIdentity,
+  prepareRemoteManagedRuntime,
+  remoteExecutionSessionMatches,
+  type RemoteManagedRuntimeAsset,
+} from "./remote-managed-runtime.js";
+import { parseSshRemoteExecutionSpec, runSshCommand, shellQuote } from "./ssh.js";
+import {
+  ensureCommandResolvable,
+  resolveCommandForLogs,
+  runChildProcess,
+  type RunProcessResult,
+  type TerminalResultCleanupOptions,
+} from "./server-utils.js";
+
+export interface AdapterLocalExecutionTarget {
+  kind: "local";
+  environmentId?: string | null;
+  leaseId?: string | null;
+}
+
+export interface AdapterSshExecutionTarget {
+  kind: "remote";
+  transport: "ssh";
+  environmentId?: string | null;
+  leaseId?: string | null;
+  remoteCwd: string;
+  paperclipApiUrl?: string | null;
+  spec: SshRemoteExecutionSpec;
+}
+
+export type AdapterExecutionTarget =
+  | AdapterLocalExecutionTarget
+  | AdapterSshExecutionTarget;
+
+export type AdapterRemoteExecutionSpec = SshRemoteExecutionSpec;
+
+export type AdapterManagedRuntimeAsset = RemoteManagedRuntimeAsset;
+
+export interface PreparedAdapterExecutionTargetRuntime {
+  target: AdapterExecutionTarget;
+  runtimeRootDir: string | null;
+  assetDirs: Record<string, string>;
+  restoreWorkspace(): Promise<void>;
+}
+
+export interface AdapterExecutionTargetProcessOptions {
+  cwd: string;
+  env: Record<string, string>;
+  stdin?: string;
+  timeoutSec: number;
+  graceSec: number;
+  onLog: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;
+  onSpawn?: (meta: { pid: number; processGroupId: number | null; startedAt: string }) => Promise<void>;
+  terminalResultCleanup?: TerminalResultCleanupOptions;
+}
+
+export interface AdapterExecutionTargetShellOptions {
+  cwd: string;
+  env: Record<string, string>;
+  timeoutSec?: number;
+  graceSec?: number;
+  onLog?: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;
+}
+
+function parseObject(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function readString(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function readStringMeta(parsed: Record<string, unknown>, key: string): string | null {
+  return readString(parsed[key]);
+}
+
+function isAdapterExecutionTargetInstance(value: unknown): value is AdapterExecutionTarget {
+  const parsed = parseObject(value);
+  if (parsed.kind === "local") return true;
+  if (parsed.kind !== "remote") return false;
+  if (parsed.transport === "ssh") return parseSshRemoteExecutionSpec(parseObject(parsed.spec)) !== null;
+  return false;
+}
+
+export function adapterExecutionTargetToRemoteSpec(
+  target: AdapterExecutionTarget | null | undefined,
+): AdapterRemoteExecutionSpec | null {
+  return target?.kind === "remote" && target.transport === "ssh" ? target.spec : null;
+}
+
+export function adapterExecutionTargetIsRemote(
+  target: AdapterExecutionTarget | null | undefined,
+): boolean {
+  return target?.kind === "remote";
+}
+
+export function adapterExecutionTargetUsesManagedHome(
+  target: AdapterExecutionTarget | null | undefined,
+): boolean {
+  // SSH execution targets sync the runtime assets they need into the remote cwd today,
+  // so neither local nor remote targets provision a separate managed adapter home.
+  void target;
+  return false;
+}
+
+export function adapterExecutionTargetRemoteCwd(
+  target: AdapterExecutionTarget | null | undefined,
+  localCwd: string,
+): string {
+  return target?.kind === "remote" ? target.remoteCwd : localCwd;
+}
+
+export function adapterExecutionTargetPaperclipApiUrl(
+  target: AdapterExecutionTarget | null | undefined,
+): string | null {
+  if (target?.kind !== "remote") return null;
+  return target.paperclipApiUrl ?? target.spec.paperclipApiUrl ?? null;
+}
+
+export function describeAdapterExecutionTarget(
+  target: AdapterExecutionTarget | null | undefined,
+): string {
+  if (!target || target.kind === "local") return "local environment";
+  return `SSH environment ${target.spec.username}@${target.spec.host}:${target.spec.port}`;
+}
+
+export async function ensureAdapterExecutionTargetCommandResolvable(
+  command: string,
+  target: AdapterExecutionTarget | null | undefined,
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+) {
+  await ensureCommandResolvable(command, cwd, env, {
+    remoteExecution: adapterExecutionTargetToRemoteSpec(target),
+  });
+}
+
+export async function resolveAdapterExecutionTargetCommandForLogs(
+  command: string,
+  target: AdapterExecutionTarget | null | undefined,
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+): Promise<string> {
+  return await resolveCommandForLogs(command, cwd, env, {
+    remoteExecution: adapterExecutionTargetToRemoteSpec(target),
+  });
+}
+
+export async function runAdapterExecutionTargetProcess(
+  runId: string,
+  target: AdapterExecutionTarget | null | undefined,
+  command: string,
+  args: string[],
+  options: AdapterExecutionTargetProcessOptions,
+): Promise<RunProcessResult> {
+  return await runChildProcess(runId, command, args, {
+    cwd: options.cwd,
+    env: options.env,
+    stdin: options.stdin,
+    timeoutSec: options.timeoutSec,
+    graceSec: options.graceSec,
+    onLog: options.onLog,
+    onSpawn: options.onSpawn,
+    terminalResultCleanup: options.terminalResultCleanup,
+    remoteExecution: adapterExecutionTargetToRemoteSpec(target),
+  });
+}
+
+export async function runAdapterExecutionTargetShellCommand(
+  runId: string,
+  target: AdapterExecutionTarget | null | undefined,
+  command: string,
+  options: AdapterExecutionTargetShellOptions,
+): Promise<RunProcessResult> {
+  const onLog = options.onLog ?? (async () => {});
+  if (target?.kind === "remote") {
+    const startedAt = new Date().toISOString();
+    try {
+      const result = await runSshCommand(target.spec, `sh -lc ${shellQuote(command)}`, {
+        timeoutMs: (options.timeoutSec ?? 15) * 1000,
+      });
+      if (result.stdout) await onLog("stdout", result.stdout);
+      if (result.stderr) await onLog("stderr", result.stderr);
+      return {
+        exitCode: 0,
+        signal: null,
+        timedOut: false,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        pid: null,
+        startedAt,
+      };
+    } catch (error) {
+      const timedOutError = error as NodeJS.ErrnoException & {
+        stdout?: string;
+        stderr?: string;
+        signal?: string | null;
+      };
+      const stdout = timedOutError.stdout ?? "";
+      const stderr = timedOutError.stderr ?? "";
+      if (typeof timedOutError.code === "number") {
+        if (stdout) await onLog("stdout", stdout);
+        if (stderr) await onLog("stderr", stderr);
+        return {
+          exitCode: timedOutError.code,
+          signal: timedOutError.signal ?? null,
+          timedOut: false,
+          stdout,
+          stderr,
+          pid: null,
+          startedAt,
+        };
+      }
+      if (timedOutError.code !== "ETIMEDOUT") {
+        throw error;
+      }
+      if (stdout) await onLog("stdout", stdout);
+      if (stderr) await onLog("stderr", stderr);
+      return {
+        exitCode: null,
+        signal: timedOutError.signal ?? null,
+        timedOut: true,
+        stdout,
+        stderr,
+        pid: null,
+        startedAt,
+      };
+    }
+  }
+
+  return await runAdapterExecutionTargetProcess(
+    runId,
+    target,
+    "sh",
+    ["-lc", command],
+    {
+      cwd: options.cwd,
+      env: options.env,
+      timeoutSec: options.timeoutSec ?? 15,
+      graceSec: options.graceSec ?? 5,
+      onLog,
+    },
+  );
+}
+
+export async function readAdapterExecutionTargetHomeDir(
+  runId: string,
+  target: AdapterExecutionTarget | null | undefined,
+  options: AdapterExecutionTargetShellOptions,
+): Promise<string | null> {
+  const result = await runAdapterExecutionTargetShellCommand(
+    runId,
+    target,
+    'printf %s "$HOME"',
+    options,
+  );
+  const homeDir = result.stdout.trim();
+  return homeDir.length > 0 ? homeDir : null;
+}
+
+export async function ensureAdapterExecutionTargetFile(
+  runId: string,
+  target: AdapterExecutionTarget | null | undefined,
+  filePath: string,
+  options: AdapterExecutionTargetShellOptions,
+): Promise<void> {
+  await runAdapterExecutionTargetShellCommand(
+    runId,
+    target,
+    `mkdir -p ${shellQuote(path.posix.dirname(filePath))} && : > ${shellQuote(filePath)}`,
+    options,
+  );
+}
+
+export function adapterExecutionTargetSessionIdentity(
+  target: AdapterExecutionTarget | null | undefined,
+): Record<string, unknown> | null {
+  if (!target || target.kind === "local") return null;
+  return buildRemoteExecutionSessionIdentity(target.spec);
+}
+
+export function adapterExecutionTargetSessionMatches(
+  saved: unknown,
+  target: AdapterExecutionTarget | null | undefined,
+): boolean {
+  if (!target || target.kind === "local") {
+    return Object.keys(parseObject(saved)).length === 0;
+  }
+  return remoteExecutionSessionMatches(saved, target.spec);
+}
+
+export function parseAdapterExecutionTarget(value: unknown): AdapterExecutionTarget | null {
+  const parsed = parseObject(value);
+  const kind = readStringMeta(parsed, "kind");
+
+  if (kind === "local") {
+    return {
+      kind: "local",
+      environmentId: readStringMeta(parsed, "environmentId"),
+      leaseId: readStringMeta(parsed, "leaseId"),
+    };
+  }
+
+  if (kind === "remote" && readStringMeta(parsed, "transport") === "ssh") {
+    const spec = parseSshRemoteExecutionSpec(parseObject(parsed.spec));
+    if (!spec) return null;
+    return {
+      kind: "remote",
+      transport: "ssh",
+      environmentId: readStringMeta(parsed, "environmentId"),
+      leaseId: readStringMeta(parsed, "leaseId"),
+      remoteCwd: spec.remoteCwd,
+      paperclipApiUrl: readStringMeta(parsed, "paperclipApiUrl") ?? spec.paperclipApiUrl ?? null,
+      spec,
+    };
+  }
+
+  return null;
+}
+
+export function adapterExecutionTargetFromRemoteExecution(
+  remoteExecution: unknown,
+  metadata: Pick<AdapterLocalExecutionTarget, "environmentId" | "leaseId"> = {},
+): AdapterExecutionTarget | null {
+  const parsed = parseObject(remoteExecution);
+  const ssh = parseSshRemoteExecutionSpec(parsed);
+  if (ssh) {
+    return {
+      kind: "remote",
+      transport: "ssh",
+      environmentId: metadata.environmentId ?? null,
+      leaseId: metadata.leaseId ?? null,
+      remoteCwd: ssh.remoteCwd,
+      paperclipApiUrl: ssh.paperclipApiUrl ?? null,
+      spec: ssh,
+    };
+  }
+
+  return null;
+}
+
+export function readAdapterExecutionTarget(input: {
+  executionTarget?: unknown;
+  legacyRemoteExecution?: unknown;
+}): AdapterExecutionTarget | null {
+  if (isAdapterExecutionTargetInstance(input.executionTarget)) {
+    return input.executionTarget;
+  }
+  return (
+    parseAdapterExecutionTarget(input.executionTarget) ??
+    adapterExecutionTargetFromRemoteExecution(input.legacyRemoteExecution)
+  );
+}
+
+export async function prepareAdapterExecutionTargetRuntime(input: {
+  target: AdapterExecutionTarget | null | undefined;
+  adapterKey: string;
+  workspaceLocalDir: string;
+  workspaceExclude?: string[];
+  preserveAbsentOnRestore?: string[];
+  assets?: AdapterManagedRuntimeAsset[];
+  installCommand?: string | null;
+}): Promise<PreparedAdapterExecutionTargetRuntime> {
+  const target = input.target ?? { kind: "local" as const };
+  if (target.kind === "local") {
+    return {
+      target,
+      runtimeRootDir: null,
+      assetDirs: {},
+      restoreWorkspace: async () => {},
+    };
+  }
+
+  const prepared = await prepareRemoteManagedRuntime({
+    spec: target.spec,
+    adapterKey: input.adapterKey,
+    workspaceLocalDir: input.workspaceLocalDir,
+    assets: input.assets,
+  });
+  return {
+    target,
+    runtimeRootDir: prepared.runtimeRootDir,
+    assetDirs: prepared.assetDirs,
+    restoreWorkspace: prepared.restoreWorkspace,
+  };
+}
+
+export function runtimeAssetDir(
+  prepared: Pick<PreparedAdapterExecutionTargetRuntime, "assetDirs">,
+  key: string,
+  fallbackRemoteCwd: string,
+): string {
+  return prepared.assetDirs[key] ?? path.posix.join(fallbackRemoteCwd, ".paperclip-runtime", key);
+}
--- a/packages/adapter-utils/src/remote-managed-runtime.ts
+++ b/packages/adapter-utils/src/remote-managed-runtime.ts
@ -0,0 +1,118 @@
+import path from "node:path";
+import {
+  type SshRemoteExecutionSpec,
+  prepareWorkspaceForSshExecution,
+  restoreWorkspaceFromSshExecution,
+  syncDirectoryToSsh,
+} from "./ssh.js";
+
+export interface RemoteManagedRuntimeAsset {
+  key: string;
+  localDir: string;
+  followSymlinks?: boolean;
+  exclude?: string[];
+}
+
+export interface PreparedRemoteManagedRuntime {
+  spec: SshRemoteExecutionSpec;
+  workspaceLocalDir: string;
+  workspaceRemoteDir: string;
+  runtimeRootDir: string;
+  assetDirs: Record<string, string>;
+  restoreWorkspace(): Promise<void>;
+}
+
+function asObject(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function asString(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function asNumber(value: unknown): number {
+  return typeof value === "number" ? value : Number(value);
+}
+
+export function buildRemoteExecutionSessionIdentity(spec: SshRemoteExecutionSpec | null) {
+  if (!spec) return null;
+  return {
+    transport: "ssh",
+    host: spec.host,
+    port: spec.port,
+    username: spec.username,
+    remoteCwd: spec.remoteCwd,
+    ...(spec.paperclipApiUrl ? { paperclipApiUrl: spec.paperclipApiUrl } : {}),
+  } as const;
+}
+
+export function remoteExecutionSessionMatches(saved: unknown, current: SshRemoteExecutionSpec | null): boolean {
+  const currentIdentity = buildRemoteExecutionSessionIdentity(current);
+  if (!currentIdentity) return false;
+
+  const parsedSaved = asObject(saved);
+  return (
+    asString(parsedSaved.transport) === currentIdentity.transport &&
+    asString(parsedSaved.host) === currentIdentity.host &&
+    asNumber(parsedSaved.port) === currentIdentity.port &&
+    asString(parsedSaved.username) === currentIdentity.username &&
+    asString(parsedSaved.remoteCwd) === currentIdentity.remoteCwd &&
+    asString(parsedSaved.paperclipApiUrl) === asString(currentIdentity.paperclipApiUrl)
+  );
+}
+
+export async function prepareRemoteManagedRuntime(input: {
+  spec: SshRemoteExecutionSpec;
+  adapterKey: string;
+  workspaceLocalDir: string;
+  workspaceRemoteDir?: string;
+  assets?: RemoteManagedRuntimeAsset[];
+}): Promise<PreparedRemoteManagedRuntime> {
+  const workspaceRemoteDir = input.workspaceRemoteDir ?? input.spec.remoteCwd;
+  const runtimeRootDir = path.posix.join(workspaceRemoteDir, ".paperclip-runtime", input.adapterKey);
+
+  await prepareWorkspaceForSshExecution({
+    spec: input.spec,
+    localDir: input.workspaceLocalDir,
+    remoteDir: workspaceRemoteDir,
+  });
+
+  const assetDirs: Record<string, string> = {};
+  try {
+    for (const asset of input.assets ?? []) {
+      const remoteDir = path.posix.join(runtimeRootDir, asset.key);
+      assetDirs[asset.key] = remoteDir;
+      await syncDirectoryToSsh({
+        spec: input.spec,
+        localDir: asset.localDir,
+        remoteDir,
+        followSymlinks: asset.followSymlinks,
+        exclude: asset.exclude,
+      });
+    }
+  } catch (error) {
+    await restoreWorkspaceFromSshExecution({
+      spec: input.spec,
+      localDir: input.workspaceLocalDir,
+      remoteDir: workspaceRemoteDir,
+    });
+    throw error;
+  }
+
+  return {
+    spec: input.spec,
+    workspaceLocalDir: input.workspaceLocalDir,
+    workspaceRemoteDir,
+    runtimeRootDir,
+    assetDirs,
+    restoreWorkspace: async () => {
+      await restoreWorkspaceFromSshExecution({
+        spec: input.spec,
+        localDir: input.workspaceLocalDir,
+        remoteDir: workspaceRemoteDir,
+      });
+    },
+  };
+}
--- a/packages/adapter-utils/src/server-utils.ts
+++ b/packages/adapter-utils/src/server-utils.ts
@ -1,6 +1,7 @@
 import { spawn, type ChildProcess } from "node:child_process";
 import { constants as fsConstants, promises as fs, type Dirent } from "node:fs";
 import path from "node:path";
+import { buildSshSpawnTarget, type SshRemoteExecutionSpec } from "./ssh.js";
 import type {
  AdapterSkillEntry,
  AdapterSkillSnapshot,
@ -30,8 +31,12 @@ interface RunningProcess {
 interface SpawnTarget {
  command: string;
  args: string[];
+  cwd?: string;
+  cleanup?: () => Promise<void>;
 }

+type RemoteExecutionSpec = SshRemoteExecutionSpec;
+
 type ChildProcessWithEvents = ChildProcess & {
  on(event: "error", listener: (err: Error) => void): ChildProcess;
  on(
@ -806,11 +811,26 @@ export function buildPaperclipEnv(agent: { id: string; companyId: string }): Rec
    process.env.PAPERCLIP_LISTEN_HOST ?? process.env.HOST ?? "localhost",
  );
  const runtimePort = process.env.PAPERCLIP_LISTEN_PORT ?? process.env.PORT ?? "3100";
-  const apiUrl = process.env.PAPERCLIP_API_URL ?? `http://${runtimeHost}:${runtimePort}`;
+  const apiUrl =
+    process.env.PAPERCLIP_RUNTIME_API_URL ??
+    process.env.PAPERCLIP_API_URL ??
+    `http://${runtimeHost}:${runtimePort}`;
  vars.PAPERCLIP_API_URL = apiUrl;
  return vars;
 }

+export function sanitizeInheritedPaperclipEnv(baseEnv: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = { ...baseEnv };
+  for (const key of Object.keys(env)) {
+    if (!key.startsWith("PAPERCLIP_")) continue;
+    if (key === "PAPERCLIP_RUNTIME_API_URL") continue;
+    if (key === "PAPERCLIP_LISTEN_HOST") continue;
+    if (key === "PAPERCLIP_LISTEN_PORT") continue;
+    delete env[key];
+  }
+  return env;
+}
+
 export function defaultPathForPlatform() {
  if (process.platform === "win32") {
    return "C:\\Windows\\System32;C:\\Windows;C:\\Windows\\System32\\Wbem";
@ -859,7 +879,18 @@ async function resolveCommandPath(command: string, cwd: string, env: NodeJS.Proc
  return null;
 }

-export async function resolveCommandForLogs(command: string, cwd: string, env: NodeJS.ProcessEnv): Promise<string> {
+export async function resolveCommandForLogs(
+  command: string,
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+  options: {
+    remoteExecution?: RemoteExecutionSpec | null;
+  } = {},
+): Promise<string> {
+  const remote = options.remoteExecution ?? null;
+  if (remote) {
+    return `ssh://${remote.username}@${remote.host}:${remote.port}/${remote.remoteCwd} :: ${command}`;
+  }
  return (await resolveCommandPath(command, cwd, env)) ?? command;
 }

@ -879,7 +910,33 @@ async function resolveSpawnTarget(
  args: string[],
  cwd: string,
  env: NodeJS.ProcessEnv,
+  options: {
+    remoteExecution?: RemoteExecutionSpec | null;
+    remoteEnv?: Record<string, string> | null;
+  } = {},
 ): Promise<SpawnTarget> {
+  const remote = options.remoteExecution ?? null;
+  if (remote) {
+    const sshResolved = await resolveCommandPath("ssh", process.cwd(), env);
+    if (!sshResolved) {
+      throw new Error('Command not found in PATH: "ssh"');
+    }
+    const spawnTarget = await buildSshSpawnTarget({
+      spec: remote,
+      command,
+      args,
+      env: Object.fromEntries(
+        Object.entries(options.remoteEnv ?? {}).filter((entry): entry is [string, string] => typeof entry[1] === "string"),
+      ),
+    });
+    return {
+      command: sshResolved,
+      args: spawnTarget.args,
+      cwd: process.cwd(),
+      cleanup: spawnTarget.cleanup,
+    };
+  }
+
  const resolved = await resolveCommandPath(command, cwd, env);
  const executable = resolved ?? command;

@ -1306,7 +1363,19 @@ export async function removeMaintainerOnlySkillSymlinks(
  }
 }

-export async function ensureCommandResolvable(command: string, cwd: string, env: NodeJS.ProcessEnv) {
+export async function ensureCommandResolvable(
+  command: string,
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+  options: {
+    remoteExecution?: RemoteExecutionSpec | null;
+  } = {},
+) {
+  if (options.remoteExecution) {
+    const resolvedSsh = await resolveCommandPath("ssh", process.cwd(), env);
+    if (resolvedSsh) return;
+    throw new Error('Command not found in PATH: "ssh"');
+  }
  const resolved = await resolveCommandPath(command, cwd, env);
  if (resolved) return;
  if (command.includes("/") || command.includes("\\")) {
@ -1330,12 +1399,15 @@ export async function runChildProcess(
    onSpawn?: (meta: { pid: number; processGroupId: number | null; startedAt: string }) => Promise<void>;
    terminalResultCleanup?: TerminalResultCleanupOptions;
    stdin?: string;
+    remoteExecution?: RemoteExecutionSpec | null;
  },
 ): Promise<RunProcessResult> {
  const onLogError = opts.onLogError ?? ((err, id, msg) => console.warn({ err, runId: id }, msg));
-
  return new Promise<RunProcessResult>((resolve, reject) => {
-    const rawMerged: NodeJS.ProcessEnv = { ...process.env, ...opts.env };
+    const rawMerged: NodeJS.ProcessEnv = {
+      ...sanitizeInheritedPaperclipEnv(process.env),
+      ...opts.env,
+    };

    // Strip Claude Code nesting-guard env vars so spawned `claude` processes
    // don't refuse to start with "cannot be launched inside another session".
@ -1353,10 +1425,13 @@ export async function runChildProcess(
    }

    const mergedEnv = ensurePathInEnv(rawMerged);
-    void resolveSpawnTarget(command, args, opts.cwd, mergedEnv)
+    void resolveSpawnTarget(command, args, opts.cwd, mergedEnv, {
+      remoteExecution: opts.remoteExecution ?? null,
+      remoteEnv: opts.remoteExecution ? opts.env : null,
+    })
      .then((target) => {
        const child = spawn(target.command, target.args, {
-          cwd: opts.cwd,
+          cwd: target.cwd ?? opts.cwd,
          env: mergedEnv,
          detached: process.platform !== "win32",
          shell: false,
@ -1484,6 +1559,7 @@ export async function runChildProcess(
          if (timeout) clearTimeout(timeout);
          clearTerminalCleanupTimers();
          runningProcesses.delete(runId);
+          void target.cleanup?.();
          const errno = (err as NodeJS.ErrnoException).code;
          const pathValue = mergedEnv.PATH ?? mergedEnv.Path ?? "";
          const msg =
@ -1502,15 +1578,19 @@ export async function runChildProcess(
          clearTerminalCleanupTimers();
          runningProcesses.delete(runId);
          void logChain.finally(() => {
-            resolve({
-              exitCode: code,
-              signal,
-              timedOut,
-              stdout,
-              stderr,
-              pid: child.pid ?? null,
-              startedAt,
-            });
+            void Promise.resolve()
+              .then(() => target.cleanup?.())
+              .finally(() => {
+              resolve({
+                exitCode: code,
+                signal,
+                timedOut,
+                stdout,
+                stderr,
+                pid: child.pid ?? null,
+                startedAt,
+              });
+              });
          });
        });
      })
--- a/packages/adapter-utils/src/ssh-fixture.test.ts
+++ b/packages/adapter-utils/src/ssh-fixture.test.ts
@ -0,0 +1,275 @@
+import { execFile } from "node:child_process";
+import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  buildSshSpawnTarget,
+  buildSshEnvLabFixtureConfig,
+  getSshEnvLabSupport,
+  prepareWorkspaceForSshExecution,
+  readSshEnvLabFixtureStatus,
+  restoreWorkspaceFromSshExecution,
+  runSshCommand,
+  syncDirectoryToSsh,
+  startSshEnvLabFixture,
+  stopSshEnvLabFixture,
+} from "./ssh.js";
+
+async function git(cwd: string, args: string[]): Promise<string> {
+  return await new Promise((resolve, reject) => {
+    execFile("git", ["-C", cwd, ...args], (error, stdout, stderr) => {
+      if (error) {
+        reject(new Error((stderr || stdout || error.message).trim()));
+        return;
+      }
+      resolve(stdout.trim());
+    });
+  });
+}
+
+describe("ssh env-lab fixture", () => {
+  const cleanupDirs: string[] = [];
+
+  afterEach(async () => {
+    while (cleanupDirs.length > 0) {
+      const dir = cleanupDirs.pop();
+      if (!dir) continue;
+      await rm(dir, { recursive: true, force: true }).catch(() => undefined);
+    }
+  });
+
+  it("starts an isolated sshd fixture and executes commands through it", async () => {
+    const support = await getSshEnvLabSupport();
+    if (!support.supported) {
+      console.warn(
+        `Skipping SSH env-lab fixture test: ${support.reason ?? "unsupported environment"}`,
+      );
+      return;
+    }
+
+    const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-fixture-"));
+    cleanupDirs.push(rootDir);
+    const statePath = path.join(rootDir, "state.json");
+
+    const started = await startSshEnvLabFixture({ statePath });
+    const config = await buildSshEnvLabFixtureConfig(started);
+    const quotedWorkspace = JSON.stringify(started.workspaceDir);
+    const result = await runSshCommand(
+      config,
+      `sh -lc 'cd ${quotedWorkspace} && pwd'`,
+    );
+
+    expect(result.stdout.trim()).toBe(started.workspaceDir);
+    const status = await readSshEnvLabFixtureStatus(statePath);
+    expect(status.running).toBe(true);
+
+    await stopSshEnvLabFixture(statePath);
+
+    const stopped = await readSshEnvLabFixtureStatus(statePath);
+    expect(stopped.running).toBe(false);
+  });
+
+  it("does not treat an unrelated reused pid as the running fixture", async () => {
+    const support = await getSshEnvLabSupport();
+    if (!support.supported) {
+      console.warn(
+        `Skipping SSH env-lab fixture test: ${support.reason ?? "unsupported environment"}`,
+      );
+      return;
+    }
+
+    const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-fixture-"));
+    cleanupDirs.push(rootDir);
+    const statePath = path.join(rootDir, "state.json");
+
+    const started = await startSshEnvLabFixture({ statePath });
+    await stopSshEnvLabFixture(statePath);
+    await mkdir(path.dirname(statePath), { recursive: true });
+
+    await writeFile(
+      statePath,
+      JSON.stringify({ ...started, pid: process.pid }, null, 2),
+      { mode: 0o600 },
+    );
+
+    const staleStatus = await readSshEnvLabFixtureStatus(statePath);
+    expect(staleStatus.running).toBe(false);
+
+    const restarted = await startSshEnvLabFixture({ statePath });
+    expect(restarted.pid).not.toBe(process.pid);
+
+    await stopSshEnvLabFixture(statePath);
+  });
+
+  it("rejects invalid environment variable keys when constructing SSH spawn targets", async () => {
+    await expect(
+      buildSshSpawnTarget({
+        spec: {
+          host: "ssh.example.test",
+          port: 22,
+          username: "ssh-user",
+          remoteCwd: "/srv/paperclip/workspace",
+          remoteWorkspacePath: "/srv/paperclip/workspace",
+          privateKey: null,
+          knownHosts: null,
+          strictHostKeyChecking: true,
+        },
+        command: "env",
+        args: [],
+        env: {
+          "BAD KEY": "value",
+        },
+      }),
+    ).rejects.toThrow("Invalid SSH environment variable key: BAD KEY");
+  });
+
+  it("syncs a local directory into the remote fixture workspace", async () => {
+    const support = await getSshEnvLabSupport();
+    if (!support.supported) {
+      console.warn(
+        `Skipping SSH env-lab fixture test: ${support.reason ?? "unsupported environment"}`,
+      );
+      return;
+    }
+
+    const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-fixture-"));
+    cleanupDirs.push(rootDir);
+    const statePath = path.join(rootDir, "state.json");
+    const localDir = path.join(rootDir, "local-overlay");
+
+    await mkdir(localDir, { recursive: true });
+    await writeFile(path.join(localDir, "message.txt"), "hello from paperclip\n", "utf8");
+    await writeFile(path.join(localDir, "._message.txt"), "should never sync\n", "utf8");
+
+    const started = await startSshEnvLabFixture({ statePath });
+    const config = await buildSshEnvLabFixtureConfig(started);
+    const remoteDir = path.posix.join(started.workspaceDir, "overlay");
+
+    await syncDirectoryToSsh({
+      spec: {
+        ...config,
+        remoteCwd: started.workspaceDir,
+      },
+      localDir,
+      remoteDir,
+    });
+
+    const result = await runSshCommand(
+      config,
+      `sh -lc 'cat ${JSON.stringify(path.posix.join(remoteDir, "message.txt"))} && if [ -e ${JSON.stringify(path.posix.join(remoteDir, "._message.txt"))} ]; then echo appledouble-present; fi'`,
+    );
+
+    expect(result.stdout).toContain("hello from paperclip");
+    expect(result.stdout).not.toContain("appledouble-present");
+  });
+
+  it("can dereference local symlinks while syncing to the remote fixture", async () => {
+    const support = await getSshEnvLabSupport();
+    if (!support.supported) {
+      console.warn(
+        `Skipping SSH symlink sync test: ${support.reason ?? "unsupported environment"}`,
+      );
+      return;
+    }
+
+    const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-fixture-"));
+    cleanupDirs.push(rootDir);
+    const statePath = path.join(rootDir, "state.json");
+    const sourceDir = path.join(rootDir, "source");
+    const localDir = path.join(rootDir, "local-overlay");
+
+    await mkdir(sourceDir, { recursive: true });
+    await mkdir(localDir, { recursive: true });
+    await writeFile(path.join(sourceDir, "auth.json"), "{\"token\":\"secret\"}\n", "utf8");
+    await symlink(path.join(sourceDir, "auth.json"), path.join(localDir, "auth.json"));
+
+    const started = await startSshEnvLabFixture({ statePath });
+    const config = await buildSshEnvLabFixtureConfig(started);
+    const remoteDir = path.posix.join(started.workspaceDir, "overlay-follow-links");
+
+    await syncDirectoryToSsh({
+      spec: {
+        ...config,
+        remoteCwd: started.workspaceDir,
+      },
+      localDir,
+      remoteDir,
+      followSymlinks: true,
+    });
+
+    const result = await runSshCommand(
+      config,
+      `sh -lc 'if [ -L ${JSON.stringify(path.posix.join(remoteDir, "auth.json"))} ]; then echo symlink; else echo regular; fi && cat ${JSON.stringify(path.posix.join(remoteDir, "auth.json"))}'`,
+    );
+
+    expect(result.stdout).toContain("regular");
+    expect(result.stdout).toContain("{\"token\":\"secret\"}");
+  });
+
+  it("round-trips a git workspace through the SSH fixture", async () => {
+    const support = await getSshEnvLabSupport();
+    if (!support.supported) {
+      console.warn(
+        `Skipping SSH workspace round-trip test: ${support.reason ?? "unsupported environment"}`,
+      );
+      return;
+    }
+
+    const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-fixture-"));
+    cleanupDirs.push(rootDir);
+    const statePath = path.join(rootDir, "state.json");
+    const localRepo = path.join(rootDir, "local-workspace");
+
+    await mkdir(localRepo, { recursive: true });
+    await git(localRepo, ["init", "-b", "main"]);
+    await git(localRepo, ["config", "user.name", "Paperclip Test"]);
+    await git(localRepo, ["config", "user.email", "test@paperclip.dev"]);
+    await writeFile(path.join(localRepo, "tracked.txt"), "base\n", "utf8");
+    await writeFile(path.join(localRepo, "._tracked.txt"), "should stay local only\n", "utf8");
+    await git(localRepo, ["add", "tracked.txt"]);
+    await git(localRepo, ["commit", "-m", "initial"]);
+    const originalHead = await git(localRepo, ["rev-parse", "HEAD"]);
+    await writeFile(path.join(localRepo, "tracked.txt"), "dirty local\n", "utf8");
+    await writeFile(path.join(localRepo, "untracked.txt"), "from local\n", "utf8");
+
+    const started = await startSshEnvLabFixture({ statePath });
+    const config = await buildSshEnvLabFixtureConfig(started);
+    const spec = {
+      ...config,
+      remoteCwd: started.workspaceDir,
+    } as const;
+
+    await prepareWorkspaceForSshExecution({
+      spec,
+      localDir: localRepo,
+      remoteDir: started.workspaceDir,
+    });
+
+    const remoteStatus = await runSshCommand(
+      config,
+      `sh -lc 'cd ${JSON.stringify(started.workspaceDir)} && git status --short'`,
+    );
+    expect(remoteStatus.stdout).toContain("M tracked.txt");
+    expect(remoteStatus.stdout).toContain("?? untracked.txt");
+    expect(remoteStatus.stdout).not.toContain("._tracked.txt");
+
+    await runSshCommand(
+      config,
+      `sh -lc 'cd ${JSON.stringify(started.workspaceDir)} && git config user.name "Paperclip SSH" && git config user.email "ssh@paperclip.dev" && git add tracked.txt untracked.txt && git commit -m "remote update" >/dev/null && printf "remote dirty\\n" > tracked.txt && printf "remote extra\\n" > remote-only.txt'`,
+      { timeoutMs: 30_000, maxBuffer: 256 * 1024 },
+    );
+
+    await restoreWorkspaceFromSshExecution({
+      spec,
+      localDir: localRepo,
+      remoteDir: started.workspaceDir,
+    });
+
+    const restoredHead = await git(localRepo, ["rev-parse", "HEAD"]);
+    expect(restoredHead).not.toBe(originalHead);
+    expect(await git(localRepo, ["log", "-1", "--pretty=%s"])).toBe("remote update");
+    expect(await git(localRepo, ["status", "--short"])).toContain("M tracked.txt");
+    expect(await git(localRepo, ["status", "--short"])).not.toContain("._tracked.txt");
+  });
+});
--- a/packages/adapter-utils/src/ssh.ts
+++ b/packages/adapter-utils/src/ssh.ts
--- a/packages/adapter-utils/src/types.ts
+++ b/packages/adapter-utils/src/types.ts
@ -2,6 +2,9 @@
 // Minimal adapter-facing interfaces (no drizzle dependency)
 // ---------------------------------------------------------------------------

+import type { SshRemoteExecutionSpec } from "./ssh.js";
+import type { AdapterExecutionTarget } from "./execution-target.js";
+
 export interface AdapterAgent {
  id: string;
  companyId: string;
@ -118,6 +121,14 @@ export interface AdapterExecutionContext {
  runtime: AdapterRuntime;
  config: Record<string, unknown>;
  context: Record<string, unknown>;
+  executionTarget?: AdapterExecutionTarget | null;
+  /**
+   * Legacy remote transport view. Prefer `executionTarget`, which is the
+   * provider-neutral contract produced by core runtime code.
+   */
+  executionTransport?: {
+    remoteExecution?: Record<string, unknown> | null;
+  };
  onLog: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;
  onMeta?: (meta: AdapterInvocationMeta) => Promise<void>;
  onSpawn?: (meta: { pid: number; processGroupId: number | null; startedAt: string }) => Promise<void>;
@ -417,6 +428,7 @@ export interface CreateConfigValues {
  workspaceBranchTemplate?: string;
  worktreeParentDir?: string;
  runtimeServicesJson?: string;
+  defaultEnvironmentId?: string;
  maxTurnsPerRun: number;
  heartbeatEnabled: boolean;
  intervalSec: number;