{"record":{"id":"25c8b5ac24326091","repo":"paperclipai/paperclip","slug":"local-process-filesystem-and-network-scopes-are-cu","errorCode":null,"errorMessage":"Local process filesystem and network scopes are currently supported only on Linux.","messagePattern":"Local process filesystem and network scopes are currently supported only on Linux\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/adapter-utils/src/local-process-sandbox.ts","lineNumber":348,"sourceCode":"  process.on(\"SIGTERM\", () => forward(\"SIGTERM\"));\n  process.on(\"SIGINT\", () => forward(\"SIGINT\"));\n  child.on(\"exit\", (code, signal) => server.close(() => {\n    if (signal) process.kill(process.pid, signal);\n    else process.exit(code == null ? 1 : code);\n  }));\n});\n`;\n  return source.trimStart();\n}\n\nexport async function buildLocalProcessSandboxSpawnTarget(input: {\n  executable: string;\n  args: string[];\n  cwd: string;\n  options: LocalProcessSandboxOptions;\n}): Promise<LocalProcessSandboxSpawnTarget> {\n  if (process.platform !== \"linux\") {\n    throw new Error(\"Local process filesystem and network scopes are currently supported only on Linux.\");\n  }\n  const filesystemScope = input.options.filesystemScope ?? null;\n  const networkScope = input.options.networkScope ?? null;\n  if (!filesystemScope && !networkScope) throw new Error(\"Local process sandbox requires a filesystem or network scope.\");\n\n  const workspaceDir = normalizeAbsolutePath(input.options.workspaceDir, \"Sandbox workspaceDir\");\n  const cwd = normalizeAbsolutePath(input.cwd, \"Sandbox cwd\");\n  if (filesystemScope === \"workspace\") {\n    const relativeCwd = path.relative(workspaceDir, cwd);\n    if (relativeCwd.startsWith(\"..\") || path.isAbsolute(relativeCwd)) {\n      throw new Error(`Sandbox cwd \"${cwd}\" must be inside workspaceDir \"${workspaceDir}\".`);\n    }\n    const outboundRestorePaths = (input.options.outboundRestorePaths ?? []).map((candidate, index) =>\n      normalizeAbsolutePath(candidate, `Sandbox outboundRestorePaths[${index}]`));\n    for (const [index, extraPath] of (input.options.extraPaths ?? []).entries()) {\n      if (extraPath.access !== \"rw\") continue;\n      const normalizedExtraPath = normalizeAbsolutePath(extraPath.path, `Sandbox extraPaths[${index}].path`);\n      const relativeToWorkspace = path.relative(workspaceDir, normalizedExtraPath);","sourceCodeStart":330,"sourceCodeEnd":366,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/packages/adapter-utils/src/local-process-sandbox.ts#L330-L366","documentation":"Thrown by buildLocalProcessSandboxSpawnTarget on any non-Linux platform. The sandbox is built on bubblewrap (bwrap) plus Linux namespace unsharing (--unshare-pid, --unshare-ipc, --unshare-uts, --unshare-net) and an AF_UNIX proxy socket, none of which are portable to macOS or Windows. This is a hard precondition: there is no fallback path, the function refuses to spawn.","triggerScenarios":"Running the adapter on macOS (dev laptop) or Windows and calling buildLocalProcessSandboxSpawnTarget with filesystemScope or networkScope set. The process.platform check at local-process-sandbox.ts:347 throws before any other validation runs.","commonSituations":"Engineers developing locally on macOS while production runs on Linux; CI matrix builds that include non-Linux jobs; Docker Desktop on macOS where the Node process is on the host (not in a Linux container). Note that calling inside a Linux container on a macOS host works, because process.platform inside the container reports \"linux\".","solutions":["Run the sandboxed execution inside a Linux container/VM (docker run --rm -it node:20 on macOS hosts reports platform=linux).","On non-Linux dev hosts, gate sandbox use behind a config flag and skip the scope options: leave filesystemScope and networkScope unset so the sandbox code path is not entered.","If the production target is Linux, mirror that in dev via Docker, colima, lima, or a Linux VM — do not develop sandbox configs against macOS and expect them to work.","If you must support macOS/Windows, file a feature request; the current implementation has no portability shim."],"exampleFix":"// before\nconst target = await buildLocalProcessSandboxSpawnTarget({\n  ...input,\n  options: { ...input.options, filesystemScope: \"workspace\" },\n});\n\n// after: gate by platform\nconst target = process.platform === \"linux\"\n  ? await buildLocalProcessSandboxSpawnTarget({\n      ...input,\n      options: { ...input.options, filesystemScope: \"workspace\" },\n    })\n  : { command: input.executable, args: input.args, cwd: input.cwd, env: process.env, cleanup: undefined };","handlingStrategy":"validation","validationCode":"function assertLinuxSandboxSupported(): void {\n  if (process.platform !== \"linux\") {\n    throw new Error(`Sandbox requires Linux (got ${process.platform}); run inside a Linux container or skip sandbox scopes.`);\n  }\n}\n\nassertLinuxSandboxSupported();\nconst target = await buildLocalProcessSandboxSpawnTarget(input);","typeGuard":"function supportsLocalSandbox(): boolean {\n  return process.platform === \"linux\";\n}","tryCatchPattern":"try {\n  return await buildLocalProcessSandboxSpawnTarget(input);\n} catch (error) {\n  if (error instanceof Error && error.message.includes(\"supported only on Linux\")) {\n    return { command: input.executable, args: input.args, cwd: input.cwd, env: process.env, cleanup: undefined };\n  }\n  throw error;\n}","preventionTips":["Run sandboxed execution inside a Linux container on non-Linux hosts (Docker, colima, lima).","Gate sandbox scope options by platform in your adapter so they are not set on macOS/Windows.","Mirror production (Linux) in dev via a Linux VM or container; do not develop sandbox configs against macOS."],"tags":["platform","linux","sandbox","environment"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}