{"record":{"id":"36c5175c02cedc59","repo":"paperclipai/paperclip","slug":"codex-working-directory-inside-the-host-home-requi","errorCode":null,"errorMessage":"Codex working directory inside the host HOME requires an assigned workspace","messagePattern":"Codex working directory inside the host HOME requires an assigned workspace","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/drivers/codex/codex-boundaries.ts","lineNumber":91,"sourceCode":"  if (hostHome && pathContains(resolved, hostHome)) {\n    throw new Error(\"Codex working directory cannot contain the host HOME\");\n  }\n  if (\n    hostHome &&\n    SENSITIVE_HOST_HOME_DIRECTORIES.some((directory) =>\n      pathContains(resolve(hostHome, directory), resolved),\n    )\n  ) {\n    throw new Error(\n      \"Codex working directory cannot overlap sensitive host HOME state\",\n    );\n  }\n  if (\n    hostHome &&\n    pathContains(hostHome, resolved) &&\n    (configuredRoot === undefined || configuredRoot.trim().length === 0)\n  ) {\n    throw new Error(\n      \"Codex working directory inside the host HOME requires an assigned workspace\",\n    );\n  }\n  const codexHome = canonicalConfiguredPath(environment.CODEX_HOME);\n  if (codexHome) {\n    if (\n      pathContains(resolved, codexHome) ||\n      pathContains(codexHome, resolved)\n    ) {\n      throw new Error(\"Codex working directory cannot overlap host CODEX_HOME\");\n    }\n  }\n  if (configuredRoot !== undefined && configuredRoot.trim().length > 0) {\n    const root = canonicalConfiguredPath(configuredRoot)!;\n    const pathFromRoot = relative(root, resolved);\n    if (\n      pathFromRoot === \"..\" ||\n      pathFromRoot.startsWith(`..${sep}`) ||","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/drivers/codex/codex-boundaries.ts#L73-L109","documentation":"The validator permits a working directory inside the host HOME only when it corresponds to an assigned workspace root: PAPERCLIP_WORKSPACE_CWD must be set to a non-empty value. Without that configured workspace boundary, a HOME-resident working directory cannot be proven to be a legitimate assigned workspace and is rejected.","triggerScenarios":"Passing a path under $HOME (e.g. ~/workspaces/foo) while the PAPERCLIP_WORKSPACE_CWD environment variable is unset or blank.","commonSituations":"Local development on a machine where workspaces live in the home directory but the workspace-root env var was never exported; service manager (systemd, docker) dropping the env var; switching from root-based workspaces to HOME-based without updating config.","solutions":["Set PAPERCLIP_WORKSPACE_CWD to the workspace root that contains the working directory","Move workspaces outside HOME to avoid needing the env var","Fix the service definition so PAPERCLIP_WORKSPACE_CWD is passed through to the runner"],"exampleFix":"// before\n# runner starts with only HOME set\n./paperclip-runner\n// after\nPAPERCLIP_WORKSPACE_CWD=/home/alice/workspaces ./paperclip-runner","handlingStrategy":"validation","validationCode":"const cwd = resolve(candidate);\nconst home = process.env.HOME;\nconst workspaceRoot = process.env.PAPERCLIP_WORKSPACE_CWD;\nif (home && contains(home, cwd) && (!workspaceRoot || workspaceRoot.trim() === \"\")) {\n  throw new Error(\"HOME-resident workspace requires PAPERCLIP_WORKSPACE_CWD\");\n}","typeGuard":"function homeWorkspaceConfigured(cwd: string, env: NodeJS.ProcessEnv): boolean {\n  const home = env.HOME;\n  const root = env.PAPERCLIP_WORKSPACE_CWD;\n  return !(home && contains(home, cwd)) || (!!root && root.trim().length > 0);\n}","tryCatchPattern":"try {\n  validateCodexWorkingDirectory(cwd);\n} catch (err) {\n  if (err.message.includes(\"requires an assigned workspace\")) {\n    throw new ConfigError(\"set PAPERCLIP_WORKSPACE_CWD or move workspaces outside HOME\");\n  }\n  throw err;\n}","preventionTips":["Export PAPERCLIP_WORKSPACE_CWD in the runner's service definition/systemd unit","Verify env passthrough in containers (docker -e, compose environment)","Prefer workspaces outside HOME so the constraint is moot"],"tags":["configuration","env-var","security"],"backgroundTag":"missing-env-var","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}