paperclipai/paperclip · error

Codex working directory cannot overlap host CODEX_HOME

Error message

Codex working directory cannot overlap host CODEX_HOME

What it means

The driver keeps its own state under CODEX_HOME (the Codex CLI's config/session home). If the agent working directory overlaps CODEX_HOME in either direction (working dir contains CODEX_HOME, or is inside it), the session could read or mutate provider state, so the overlap is rejected in both directions.

Solutions

1. Change the working directory so it neither contains nor sits inside CODEX_HOME
2. Move CODEX_HOME to a location disjoint from all workspace roots (e.g. /var/lib/codex)
3. Unset the stray CODEX_HOME override if it was unintentional

Example fix

// before
CODEX_HOME=/workspaces/agent-42/.codex workingDirectory=/workspaces/agent-42
// after
CODEX_HOME=/var/lib/codex workingDirectory=/workspaces/agent-42

const codexHome = process.env.CODEX_HOME;
if (codexHome && (contains(resolve(cwd), resolve(codexHome)) || contains(resolve(codexHome), resolve(cwd)))) {
  throw new Error("workspace and CODEX_HOME must be disjoint");
}

function disjointFromCodexHome(cwd: string, env: NodeJS.ProcessEnv): boolean {
  const ch = env.CODEX_HOME;
  return !ch || !(contains(resolve(cwd), resolve(ch)) || contains(resolve(ch), resolve(cwd)));
}

try {
  validateCodexWorkingDirectory(cwd);
} catch (err) {
  if (err.message.includes("cannot overlap host CODEX_HOME")) {
    throw new ConfigError(`relocate CODEX_HOME or pick a different workspace than ${cwd}`);
  }
  throw err;
}

When it happens

Trigger: Setting the working directory to $CODEX_HOME or a parent of it (e.g. HOME when CODEX_HOME=$HOME/.codex, though HOME ancestry is caught earlier), or into ~/.codex itself; or setting CODEX_HOME to a path inside the workspace.

Common situations: Developers pointing the workspace at ~/.codex to inspect Codex state; custom CODEX_HOME values that collide with the assigned workspace path; inherited environment where CODEX_HOME was repointed.

Understand the failure class

Background: Path traversal blocked: "path escapes the workspace" and "outside site root" errors when a path will not stay inside its allowed directory — this error's family across 26 libraries.

Related errors

• A trusted viewer build is required for public chat reports
• ACPX runtime executable changed while it was verified
• ACPX runtime executable could not be opened as a no-follow…
• ACPX runtime executable must be a bounded executable file
• ACPX runtime executable must be a real regular file

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

Appendix: source

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

      "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}`) ||
      isAbsolute(pathFromRoot)
    ) {
      throw new Error(
        "Codex working directory is outside the assigned workspace",
      );
    }
  }
  return resolved;
}

View on GitHub (pinned to 01ad858492)