diff --git a/docs/deploy/environment-variables.md b/docs/deploy/environment-variables.md index 70d804fc346..2489a0bd880 100644 --- a/docs/deploy/environment-variables.md +++ b/docs/deploy/environment-variables.md @@ -22,7 +22,7 @@ All environment variables that Paperclip uses for server configuration. | `PAPERCLIP_CHAT_WEBHOOK_PUBLIC_URL` | (board public origin) | Optional HTTPS origin for native chat provider webhooks when ingress and the board use different hosts. Must have no credentials, path, query, or fragment; invalid configuration refuses startup. Used only for provider callback URLs, not board links, authentication, trusted hosts, or identity confirmation. In `authenticated` mode with `private` exposure, also add the ingress hostname to `PAPERCLIP_ALLOWED_HOSTNAMES`. Otherwise the private-hostname guard rejects provider callbacks with 403 before they reach the webhook route. The guard reads `X-Forwarded-Host` before `Host`, so a reverse proxy that rewrites `Host` but forwards the original `X-Forwarded-Host` still gets 403. | | `PAPERCLIP_RUNNER_PUBLIC_URL` | (unset) | Explicit `wss://` base URL used only when a remote `paperclip_runner` target dials Paperclip directly. Paperclip appends `/api/runner/v1/connect/`; the reverse proxy must forward WebSocket upgrades for that route. This value is never inferred from request headers. Daytona ignores it and uses provider ingress. | | `PAPERCLIP_RUNNER_CA_BUNDLE_PATH` | (unset) | Optional PEM CA bundle for direct runner WSS. Platform roots remain enabled. There is no insecure TLS bypass. | -| `PAPERCLIP_RUNNER_REMOTE_BINARY_PATH` | (host build) | Host-local path to a `paperclip-runnerd` artifact built for the remote target OS and architecture. Required when Paperclip and the remote sandbox do not share a compatible platform; build metadata and the required transport mode are verified before launch. | +| `PAPERCLIP_RUNNER_REMOTE_BINARY_PATH` | (host build) | Host-local path to a `paperclip-runnerd` artifact built for the remote target OS and architecture. Required when Paperclip and the remote sandbox do not share a compatible platform; build metadata and the required transport mode are verified before launch. When the sandbox image already has a `paperclip-runnerd` with the same SHA-256, Paperclip uses that copy and does not upload this file. | | `PAPERCLIP_RUNNER_REMOTE_CODEX_PATH` | (unset) | Optional host-local path to a Codex executable built for the remote target OS and architecture. For remote Codex-backed runners, Paperclip stages and verifies this executable beside `paperclip-runnerd`. | | `PAPERCLIP_RUNNER_REMOTE_CODEX_NPM_SPEC` | (unset) | Optional pinned npm package spec (for example, `@openai/codex@0.160.0`) installed inside each fresh remote lease when its Codex harness is not baked into the sandbox image. Mutually exclusive with `PAPERCLIP_RUNNER_REMOTE_CODEX_PATH`; Paperclip verifies the installed executable before starting `runnerd`. | | `PAPERCLIP_RUNNER_REMOTE_PROVIDER_PACK_PATH` | `/opt/paperclip-runner/provider-pack` in Docker; otherwise unset | Host-local path to the immutable provider pack built by `pnpm --filter @paperclipai/paperclip-runner build:provider-pack`. Stamped standard Docker images include the pack; downstream compositions and the `cloud` target inherit it. Unstamped local Docker builds skip pack generation. The pack includes its target-built Node 24.11+ runtime, locked production dependencies, OpenCode proxy/executable, and ACPX sidecar. Remote OpenCode and ACPX fail closed without it. A preinstalled pack is accepted only when its complete digested manifest matches this build-owned pack; otherwise Paperclip stages this pack into the sandbox. | diff --git a/server/src/services/native-runtime/native-session-executor.test.ts b/server/src/services/native-runtime/native-session-executor.test.ts index 13fb4614f48..0dd70c67740 100644 --- a/server/src/services/native-runtime/native-session-executor.test.ts +++ b/server/src/services/native-runtime/native-session-executor.test.ts @@ -5400,6 +5400,11 @@ describe("remote preinstalled executable discovery", () => { expect(mayUsePreinstalledRunnerArtifact(" ")).toBe(true); expect(mayUsePreinstalledRunnerArtifact(undefined)).toBe(true); }); + + it("checks a preinstalled runnerd against a configured artifact the controller holds", () => { + expect(mayUsePreinstalledRunnerArtifact("/artifacts/paperclip-runnerd", true)).toBe(true); + expect(mayUsePreinstalledRunnerArtifact("/artifacts/paperclip-runnerd", false)).toBe(false); + }); }); describe("remote runner build metadata", () => { @@ -23175,7 +23180,7 @@ describe("runnerd provider runtime wiring", () => { }); it.each([ - ...["current", "preinstalled-exact", "preinstalled-mismatch", "preinstalled-error", "preinstalled-timeout", "stale", "missing", "retained", "retained-mismatch", "retained-error", "retained-timeout", "retained-explicit"] + ...["current", "preinstalled-exact", "preinstalled-mismatch", "preinstalled-error", "preinstalled-timeout", "preinstalled-explicit", "preinstalled-explicit-mismatch", "preinstalled-explicit-discover-fails", "stale", "missing", "retained", "retained-mismatch", "retained-error", "retained-timeout", "retained-explicit"] .map((image) => ({ image, version: "0.160.0" })), ...["0.149.0", "0.149.1", "0.153.4", "0.156.0", "0.160.1"] .map((version) => ({ image: "current", version })), @@ -23184,7 +23189,7 @@ describe("runnerd provider runtime wiring", () => { ])("uses shared Codex and the server-owned replacement artifact (image=$image, Codex=$version)", async ({ image, version }) => { const retained = image.startsWith("retained"); const exactRetained = image === "retained" || image === "retained-explicit"; - const needsReplacement = image !== "current" && image !== "preinstalled-exact" && !exactRetained; + const needsReplacement = image !== "current" && image !== "preinstalled-exact" && image !== "preinstalled-explicit" && !exactRetained; // The mocked remote executes metadata probes; artifact staging only needs bytes. // Keep this regression independent of a locally compiled Rust runner binary. const controllerArtifact = join(isolatedStateDirectory, "paperclip-runnerd"); @@ -23225,6 +23230,7 @@ describe("runnerd provider runtime wiring", () => { } else if (script === "uname -s; uname -m") { stdout = `${process.platform === "darwin" ? "Darwin" : "Linux"}\n${process.arch === "arm64" ? "arm64" : "x86_64"}\n`; } else if (script.includes("command -v paperclip-runnerd")) { + if (image === "preinstalled-explicit-discover-fails") throw new Error("sandbox provider unavailable"); stdout = image === "missing" ? "" : "/usr/local/bin/paperclip-runnerd\n"; } else if (script.includes("command -v codex")) { stdout = script.includes("/opt/paperclip-runner/bin/codex") @@ -23250,7 +23256,7 @@ describe("runnerd provider runtime wiring", () => { execution, runnerInstanceId: "runner-image-runtime", onLog, - ...(image === "retained-explicit" ? { runnerRemoteBinaryPath: controllerArtifact } : {}), + ...(image.includes("explicit") ? { runnerRemoteBinaryPath: controllerArtifact } : {}), runnerIngressAuthorized: true, runnerExecutionTarget: { kind: "remote", diff --git a/server/src/services/native-runtime/native-session-executor.ts b/server/src/services/native-runtime/native-session-executor.ts index c4a80912ee2..bee52eec15b 100644 --- a/server/src/services/native-runtime/native-session-executor.ts +++ b/server/src/services/native-runtime/native-session-executor.ts @@ -14239,8 +14239,9 @@ export function buildRemoteCodexLauncherCommand( export function mayUsePreinstalledRunnerArtifact( configuredRemoteBinaryPath: string | null | undefined, + configuredArtifactAvailable = false, ): boolean { - return !configuredRemoteBinaryPath?.trim(); + return !configuredRemoteBinaryPath?.trim() || configuredArtifactAvailable; } const RUNNERD_BUILD_METADATA_SCHEMA = @@ -19306,11 +19307,15 @@ export function createRemoteNativeArtifactPreparation(input: { ); } const explicitRemoteBinary = input.runnerRemoteBinaryPath?.trim() || null; - if (!runnerArtifactPrepared && mayUsePreinstalledRunnerArtifact(explicitRemoteBinary)) { + const controllerArtifactAvailable = existsSync(controllerRunnerBinary); + if (!runnerArtifactPrepared && + mayUsePreinstalledRunnerArtifact(explicitRemoteBinary, controllerArtifactAvailable)) { const preinstalledRunner = await measureNativeRunnerSpan( input.trace, "runner.artifact.discover", - () => discoverPreinstalledExecutable("paperclip-runnerd"), + () => explicitRemoteBinary + ? discoverPreinstalledExecutable("paperclip-runnerd").catch(() => null) + : discoverPreinstalledExecutable("paperclip-runnerd"), ); if (preinstalledRunner) { try { @@ -19319,7 +19324,7 @@ export function createRemoteNativeArtifactPreparation(input: { "runner.artifact.verify_preinstalled", () => verifyRemoteRunner(requiredMode, preinstalledRunner), ); - if (existsSync(controllerRunnerBinary) && + if (controllerArtifactAvailable && !await matchesControllerRunnerArtifact(preinstalledRunner)) { throw new Error("runner_remote_preinstalled_artifact_mismatch"); }