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.

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)

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

• Materialized OpenCode executable has unsafe permissions
• A trusted viewer build is required for public chat reports
• Trusted viewer must not use symlinks
• Unexpected trusted viewer asset
• Refusing public report symlink ${absolute}

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