Custom CreateOS API endpoints require an explicit…

Error message

Custom CreateOS API endpoints require an explicit environment API key; the host fallback is only available for https://api.sb.createos.sh.

What it means

resolveApiKey enforces that a custom (non-default) CreateOS API endpoint must carry an explicit apiKey in the environment config. Only the well-known host https://api.sb.createos.sh may omit it and fall back to the CREATEOS_API_KEY environment variable. This stops the shared/global credential from silently being sent to arbitrary third-party hosts.

Solutions

Add an explicit apiKey to the CreateOS environment config for the custom endpoint.
Or switch apiUrl back to https://api.sb.createos.sh so the CREATEOS_API_KEY env fallback is allowed.
If this endpoint is actually the official API, fix a typo/proxy prefix in apiUrl so it matches the default host exactly.

Example fix

// before
{ "apiUrl": "https://eu.createos.example/v1" } // relies on CREATEOS_API_KEY
// after
{ "apiUrl": "https://eu.createos.example/v1", "apiKey": "ck_live_..." }

Defensive patterns

Strategy: validation

Validate before calling

if (cfg.apiUrl !== 'https://api.sb.createos.sh' && !cfg.apiKey) {
  throw new Error('Custom CreateOS endpoints require an explicit apiKey in the environment config');
}

Prevention

Pair every custom apiUrl with an explicit apiKey at config-authoring time
Rely on CREATEOS_API_KEY fallback only for the default api.sb.createos.sh host
Keep a config checklist item: custom host => dedicated key

When it happens

Trigger: Calling resolveApiKey (directly or via the plugin constructor or its account method) with a config whose apiUrl is any origin other than https://api.sb.createos.sh while config.apiKey is empty/missing.

Common situations: Pointing the plugin at a self-hosted or regional CreateOS endpoint (or a loopback http://localhost dev server) and relying on the CREATEOS_API_KEY env var, which the fallback policy only permits for the default host.

Related errors

AI-assisted analysis of paperclipai/paperclip@3f1d897a7c (2026-09-18). Data as JSON: /api/errors/9e18ae6fd8234b47. Report an issue: GitHub.

Appendix: source

Thrown at packages/plugins/sandbox-providers/createos/src/config.ts:54

    throw new Error("timeoutMs must be an integer between 1 and 86400000.");
  }
  if (raw.reuseLease != null && typeof raw.reuseLease !== "boolean") {
    throw new Error("reuseLease must be a boolean.");
  }
  return {
    apiUrl: url.origin,
    apiKey: text("apiKey"),
    shape,
    rootfs: text("rootfs"),
    region: text("region"),
    timeoutMs,
    reuseLease: raw.reuseLease === true,
  };
}

export function resolveApiKey(config: CreateosConfig): string {
  if (!config.apiKey && config.apiUrl !== "https://api.sb.createos.sh") {
    throw new Error("Custom CreateOS API endpoints require an explicit environment API key; the host fallback is only available for https://api.sb.createos.sh.");
  }
  const key = config.apiKey ?? process.env.CREATEOS_API_KEY?.trim();
  if (!key || /[\r\n\0]/.test(key)) {
    throw new Error("CreateOS requires an API key in the environment config or CREATEOS_API_KEY.");
  }
  return key;
}

View on GitHub (pinned to 3f1d897a7c)