Service management is not supported on ${platform}. Use pape

Error message

Service management is not supported on ${platform}. Use paperclipai run instead.

What it means

During onboard service setup (or `paperclipai service install`), detectServiceManager maps platform -> service manager: darwin uses launchd, linux uses systemd --user. Any other platform (win32, freebsd, ...) returns { supported: false, reason: 'Service management is not supported on <platform>. Use paperclipai run instead.' }. The reason is warned only when --install-service was explicitly requested; otherwise install is silently skipped.

Source

Thrown at cli/src/onboard-service.ts:65

  options: OnboardServiceOptions,
  dependencies: Partial<OnboardServiceDependencies> = {},
): Promise<boolean> {
  const deps = { ...defaultDependencies, ...dependencies };
  if (options.installService === false) return false;

  const explicitlyRequested = options.installService === true;
  const canPrompt = options.yes !== true && deps.isInteractive();
  if (!explicitlyRequested && !canPrompt) {
    deps.info(
      "Background service not installed. Use `paperclipai onboard --install-service` or `paperclipai service install` to opt in.",
    );
    return false;
  }

  const instanceId = resolvePaperclipInstanceId();
  const detection = await deps.detect(instanceId);
  if (!detection.supported) {
    if (explicitlyRequested) deps.warn(detection.reason);
    return false;
  }

  if (!explicitlyRequested && !(await deps.confirm())) return false;

  await detection.manager.install({ startNow: true, startOnLogin: true });
  if (!explicitlyRequested && detection.manager.enableLinger && await deps.confirmLinger()) {
    await detection.manager.enableLinger();
  }
  deps.success(`Installed and started ${detection.manager.serviceName}.`);
  return true;
}

View on GitHub (pinned to 120ae5428f)

Solutions

Run Paperclip in the foreground with `paperclipai run` as the message suggests.
Wrap `paperclipai run` in an OS-native supervisor (NSSM/Task Scheduler on Windows, pm2, docker restart policy).
Drop --install-service so the unsupported path is skipped instead of warned.
Run the server on a linux/darwin host if unattended service management is a requirement.

Defensive patterns

Strategy: type-guard

Type guard

import type { ServiceManagerDetection } from "./services/service-manager.js";
function isUnsupportedPlatform(d: ServiceManagerDetection): d is { supported: false; reason: string } {
  return d.supported === false;
}
// usage
const detection = await detectServiceManager({ instanceId });
if (isUnsupportedPlatform(detection)) {
  // fall back to `paperclipai run` foreground or an OS-native supervisor
}

Prevention

Check process.platform before offering --install-service in docs/scripts targeting multiple OSes.
Narrow the ServiceManagerDetection union on supported before touching detection.manager.
On unsupported platforms, plan for foreground runs or container restart policies from the start.

When it happens

Trigger: Running `paperclipai onboard --install-service` (or service install) on Windows or any non-darwin/non-linux platform.

Common situations: Windows workstations; BSD hosts; trying the documented service flags on an OS the CLI does not manage services for.

Related errors

AI-assisted analysis of paperclipai/paperclip@120ae5428f (2026-08-18). Data as JSON: /api/errors/0341639941e4e0c6. Report an issue: GitHub.