Codex working directory inside the host HOME requires an ass

Error message

Codex working directory inside the host HOME requires an assigned workspace

What it means

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.

Source

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

  if (hostHome && pathContains(resolved, hostHome)) {
    throw new Error("Codex working directory cannot contain the host HOME");
  }
  if (
    hostHome &&
    SENSITIVE_HOST_HOME_DIRECTORIES.some((directory) =>
      pathContains(resolve(hostHome, directory), resolved),
    )
  ) {
    throw new Error(
      "Codex working directory cannot overlap sensitive host HOME state",
    );
  }
  if (
    hostHome &&
    pathContains(hostHome, resolved) &&
    (configuredRoot === undefined || configuredRoot.trim().length === 0)
  ) {
    throw new Error(
      "Codex working directory inside the host HOME requires an assigned workspace",
    );
  }
  const codexHome = canonicalConfiguredPath(environment.CODEX_HOME);
  if (codexHome) {
    if (
      pathContains(resolved, codexHome) ||
      pathContains(codexHome, resolved)
    ) {
      throw new Error("Codex working directory cannot overlap host CODEX_HOME");
    }
  }
  if (configuredRoot !== undefined && configuredRoot.trim().length > 0) {
    const root = canonicalConfiguredPath(configuredRoot)!;
    const pathFromRoot = relative(root, resolved);
    if (
      pathFromRoot === ".." ||
      pathFromRoot.startsWith(`..${sep}`) ||

View on GitHub (pinned to 01ad858492)

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

Example fix

// before
# runner starts with only HOME set
./paperclip-runner
// after
PAPERCLIP_WORKSPACE_CWD=/home/alice/workspaces ./paperclip-runner

Defensive patterns

Strategy: validation

Validate before calling

const cwd = resolve(candidate);
const home = process.env.HOME;
const workspaceRoot = process.env.PAPERCLIP_WORKSPACE_CWD;
if (home && contains(home, cwd) && (!workspaceRoot || workspaceRoot.trim() === "")) {
  throw new Error("HOME-resident workspace requires PAPERCLIP_WORKSPACE_CWD");
}

Type guard

function homeWorkspaceConfigured(cwd: string, env: NodeJS.ProcessEnv): boolean {
  const home = env.HOME;
  const root = env.PAPERCLIP_WORKSPACE_CWD;
  return !(home && contains(home, cwd)) || (!!root && root.trim().length > 0);
}

Try / catch

try {
  validateCodexWorkingDirectory(cwd);
} catch (err) {
  if (err.message.includes("requires an assigned workspace")) {
    throw new ConfigError("set PAPERCLIP_WORKSPACE_CWD or move workspaces outside HOME");
  }
  throw err;
}

Prevention

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

When it happens

Trigger: Passing a path under $HOME (e.g. ~/workspaces/foo) while the PAPERCLIP_WORKSPACE_CWD environment variable is unset or blank.

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

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/36c5175c02cedc59. Report an issue: GitHub.