paperclipai/paperclip · error · Error

Could not verify the remote ACPX runner platform.

Error message

Could not verify the remote ACPX runner platform.

What it means

Thrown by `testEnvironment` when the remote ACPX platform probe fails. For remote execution targets, the registry runs `uname -s && uname -m` via `runAdapterExecutionTargetShellCommand` with a 15s timeout; if the probe times out or exits non-zero, the remote platform cannot be verified and this error is raised.

Source

Thrown at server/src/adapters/registry.ts:415

        status: "fail" as const,
        testedAt: new Date().toISOString(),
        checks: [{
          code: profileError.code,
          level: "error" as const,
          message: profileError.message,
        }],
      };
    }
    if (profile.provider === "acpx") {
      try {
        if (profile.acpxAgent !== "claude") throw new Error("Select Codex to use the native Codex runner.");
        const target = context.executionTarget;
        if (target?.kind === "remote") {
          const probe = await runAdapterExecutionTargetShellCommand(
            `acpx-platform-${crypto.randomUUID()}`, target, "uname -s && uname -m",
            { cwd: target.remoteCwd, env: {}, timeoutSec: 15 },
          );
          if (probe.timedOut || probe.exitCode !== 0) throw new Error("Could not verify the remote ACPX runner platform.");
          const [os, arch] = probe.stdout.trim().split(/\s+/);
          if (!((os === "Linux" && arch === "x86_64") || (os === "Darwin" && ["arm64", "x86_64"].includes(arch ?? "")))) {
            throw new Error("ACPX Claude requires Linux x64 or macOS ARM64/x64.");
          }
          return {
            adapterType: "paperclip_runner", status: "warn" as const, testedAt: new Date().toISOString(),
            checks: [{ code: "acpx_remote_runtime_unverified", level: "warn" as const,
              message: "The remote platform is supported. Runtime package integrity and readiness must still be verified by the remote runner before launch." }],
          };
        }
        const { probeAcpxClaudeInstallation } = await import("@paperclipai/paperclip-runner/live");
        await probeAcpxClaudeInstallation(profile.model);
        return {
          adapterType: "paperclip_runner", status: "pass" as const, testedAt: new Date().toISOString(),
          checks: [{ code: "acpx_runtime_ready", level: "info" as const, message: "ACPX Claude runtime is installed and verified. Model access is checked when Claude runs." }],
        };
      } catch (error) {
        return {

View on GitHub (pinned to 01ad858492)

Solutions

  1. Verify the remote host is reachable (ping/SSH manually) and credentials work.
  2. Confirm `remoteCwd` exists on the remote host and the shell can execute `uname` there.
  3. Increase the 15s `timeoutSec` if the link is slow, or retry once connectivity improves.
  4. Check proxy/firewall/VPN settings between the control plane and the remote runner.

Example fix

// before
const probe = await runAdapterExecutionTargetShellCommand(
  `acpx-platform-${crypto.randomUUID()}`, target, "uname -s && uname -m",
  { cwd: target.remoteCwd, env: {}, timeoutSec: 15 },
);
// after
const probe = await runAdapterExecutionTargetShellCommand(
  `acpx-platform-${crypto.randomUUID()}`, target, "uname -s && uname -m",
  { cwd: target.remoteCwd, env: {}, timeoutSec: 60 },
);
Defensive patterns

Strategy: retry

Validate before calling

const probe = await ssh(target, "uname -s && uname -m", { timeoutSec: 15 });
if (probe.code !== 0) throw new Error("remote host unreachable before ACPX test");

Try / catch

try {
  await registry.testEnvironment(profile, context);
} catch (err) {
  if (err.message.includes("Could not verify the remote ACPX runner platform")) {
    await checkSshConnectivity(target); // diagnose then retry
  } else throw err;
}

Prevention

When it happens

Trigger: Testing an ACPX profile whose `context.executionTarget.kind === "remote"` and the shell probe returns `probe.timedOut === true` or `probe.exitCode !== 0` — e.g. SSH connectivity failure, remote shell unavailable, `uname` missing, or auth failure to the remote host.

Common situations: Remote host offline or unreachable over the network; SSH key/credentials misconfigured; remote cwd does not exist so the command fails; firewall or VPN blocking the connection; 15s timeout too short for a slow link.

Related errors

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/73b4ff8599527174. Report an issue: GitHub.