paperclipai/paperclip · error

Local process filesystem and network scopes are currently su

Error message

Local process filesystem and network scopes are currently supported only on Linux.

What it means

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.

Source

Thrown at packages/adapter-utils/src/local-process-sandbox.ts:348

  process.on("SIGTERM", () => forward("SIGTERM"));
  process.on("SIGINT", () => forward("SIGINT"));
  child.on("exit", (code, signal) => server.close(() => {
    if (signal) process.kill(process.pid, signal);
    else process.exit(code == null ? 1 : code);
  }));
});
`;
  return source.trimStart();
}

export async function buildLocalProcessSandboxSpawnTarget(input: {
  executable: string;
  args: string[];
  cwd: string;
  options: LocalProcessSandboxOptions;
}): Promise<LocalProcessSandboxSpawnTarget> {
  if (process.platform !== "linux") {
    throw new Error("Local process filesystem and network scopes are currently supported only on Linux.");
  }
  const filesystemScope = input.options.filesystemScope ?? null;
  const networkScope = input.options.networkScope ?? null;
  if (!filesystemScope && !networkScope) throw new Error("Local process sandbox requires a filesystem or network scope.");

  const workspaceDir = normalizeAbsolutePath(input.options.workspaceDir, "Sandbox workspaceDir");
  const cwd = normalizeAbsolutePath(input.cwd, "Sandbox cwd");
  if (filesystemScope === "workspace") {
    const relativeCwd = path.relative(workspaceDir, cwd);
    if (relativeCwd.startsWith("..") || path.isAbsolute(relativeCwd)) {
      throw new Error(`Sandbox cwd "${cwd}" must be inside workspaceDir "${workspaceDir}".`);
    }
    const outboundRestorePaths = (input.options.outboundRestorePaths ?? []).map((candidate, index) =>
      normalizeAbsolutePath(candidate, `Sandbox outboundRestorePaths[${index}]`));
    for (const [index, extraPath] of (input.options.extraPaths ?? []).entries()) {
      if (extraPath.access !== "rw") continue;
      const normalizedExtraPath = normalizeAbsolutePath(extraPath.path, `Sandbox extraPaths[${index}].path`);
      const relativeToWorkspace = path.relative(workspaceDir, normalizedExtraPath);

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Run the sandboxed execution inside a Linux container/VM (docker run --rm -it node:20 on macOS hosts reports platform=linux).
2. 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.
3. 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.
4. If you must support macOS/Windows, file a feature request; the current implementation has no portability shim.

Example fix

// before
const target = await buildLocalProcessSandboxSpawnTarget({
  ...input,
  options: { ...input.options, filesystemScope: "workspace" },
});

// after: gate by platform
const target = process.platform === "linux"
  ? await buildLocalProcessSandboxSpawnTarget({
      ...input,
      options: { ...input.options, filesystemScope: "workspace" },
    })
  : { command: input.executable, args: input.args, cwd: input.cwd, env: process.env, cleanup: undefined };

function assertLinuxSandboxSupported(): void {
  if (process.platform !== "linux") {
    throw new Error(`Sandbox requires Linux (got ${process.platform}); run inside a Linux container or skip sandbox scopes.`);
  }
}

assertLinuxSandboxSupported();
const target = await buildLocalProcessSandboxSpawnTarget(input);

function supportsLocalSandbox(): boolean {
  return process.platform === "linux";
}

try {
  return await buildLocalProcessSandboxSpawnTarget(input);
} catch (error) {
  if (error instanceof Error && error.message.includes("supported only on Linux")) {
    return { command: input.executable, args: input.args, cwd: input.cwd, env: process.env, cleanup: undefined };
  }
  throw error;
}

When it happens

Trigger: 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.

Common situations: 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".

Related errors

• Paperclip sandbox proxy socket path is ${pathBytes} bytes, e
• Unable to create a Linux-safe Paperclip sandbox proxy socket
• Command not found in PATH: "${command}"
• Local process confinement requires Bubblewrap, but "${reques
• ${detection.reason}

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/25c8b5ac24326091. Report an issue: GitHub.