Remote Codex working directory requires an assigned workspac

Error message

Remote Codex working directory requires an assigned workspace

What it means

When validating a remote_runner working directory, the validator requires the PAPERCLIP_WORKSPACE_CWD environment variable to be set and non-empty. The remote facade has no filesystem access, so it can only pin the working directory to an explicitly assigned workspace; without that assignment it refuses to proceed. The throw happens when environment.PAPERCLIP_WORKSPACE_CWD is missing, empty, or whitespace-only.

Source

Thrown at packages/paperclip-runner/src/drivers/codex/codex-boundaries.ts:138

function validateRemoteRunnerWorkingDirectory(
  workingDirectory: string,
  environment: NodeJS.ProcessEnv,
): string {
  if (
    !posix.isAbsolute(workingDirectory) ||
    posix.normalize(workingDirectory) !== workingDirectory ||
    /[\u0000-\u001f\u007f]/u.test(workingDirectory)
  ) {
    throw new Error(
      "Remote Codex working directory must be a normalized absolute path",
    );
  }
  if (workingDirectory === posix.parse(workingDirectory).root) {
    throw new Error("Codex working directory cannot be a filesystem root");
  }
  const configuredRoot = environment.PAPERCLIP_WORKSPACE_CWD?.trim();
  if (!configuredRoot) {
    throw new Error(
      "Remote Codex working directory requires an assigned workspace",
    );
  }
  if (
    !posix.isAbsolute(configuredRoot) ||
    posix.normalize(configuredRoot) !== configuredRoot
  ) {
    throw new Error(
      "Assigned remote workspace must be a normalized absolute path",
    );
  }
  // The controller cannot inspect a provider-owned filesystem. Pin the facade
  // to the exact remote workspace while runnerd validates existence, type, and
  // canonical identity inside the authoritative filesystem before launch.
  if (workingDirectory !== configuredRoot) {
    throw new Error(
      "Remote Codex working directory does not match the assigned workspace",
    );

View on GitHub (pinned to 01ad858492)

Solutions

Export PAPERCLIP_WORKSPACE_CWD to the normalized absolute remote workspace path (e.g. /workspaces/issue-42) in the process calling this validator.
Ensure the code path that spawns/validates the remote runner passes its environment through instead of a stripped process.env.
Provision the remote workspace and record its path before launching Codex; only launch after assignment exists.
Fix templating that renders the variable to an empty string.

Example fix

// before
spawnRunner({ cwd: workingDirectory }); // env lacks PAPERCLIP_WORKSPACE_CWD
// after
process.env.PAPERCLIP_WORKSPACE_CWD ??= "/workspaces/issue-42";
spawnRunner({ cwd: validateCodexWorkingDirectory(workingDirectory, process.env, "remote_runner") });

Defensive patterns

Strategy: validation

Validate before calling

const configuredRoot = process.env.PAPERCLIP_WORKSPACE_CWD?.trim();
if (!configuredRoot) throw new Error("PAPERCLIP_WORKSPACE_CWD must be set before remote Codex runs");

Type guard

const hasAssignedWorkspace = (env: NodeJS.ProcessEnv): boolean =>
  typeof env.PAPERCLIP_WORKSPACE_CWD === "string" && env.PAPERCLIP_WORKSPACE_CWD.trim().length > 0;

Try / catch

try {
  validateCodexWorkingDirectory(cwd, process.env, "remote_runner");
} catch (error) {
  if (error instanceof Error && error.message.includes("requires an assigned workspace")) {
    throw new Error("Set PAPERCLIP_WORKSPACE_CWD to the provisioned remote workspace path before launching remote Codex runs", { cause: error });
  }
  throw error;
}

Prevention

Include PAPERCLIP_WORKSPACE_CWD in deployment env templates and startup health checks.
Fail fast at process start when the variable is missing in remote mode.
Provision the workspace and write its path to env/config before any launch call.

When it happens

Trigger: Calling validateCodexWorkingDirectory(path, env, "remote_runner") where env.PAPERCLIP_WORKSPACE_CWD is undefined, "", or contains only whitespace (e.g. PAPERCLIP_WORKSPACE_CWD unset in the controller process, or set to " " via bad env templating).

Common situations: Starting the controller/runner service without the workspace-assignment env var in a remote provider deployment; a deployment pipeline dropping the variable; local dev configs used against a remote runner where the var is only set in production.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/fb54352aedad4b16. Report an issue: GitHub.