Codex working directory cannot overlap sensitive host HOME s

Error message

Codex working directory cannot overlap sensitive host HOME state

What it means

Beyond the HOME ancestor check, the validator blocks working directories that overlap a curated list of sensitive directories under the host HOME (things like ~/.ssh, ~/.aws, ~/.config style state). Even if the working directory is not an ancestor of HOME, landing inside one of these protected directories would expose secrets or allow tampering with host tooling.

Source

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

      );
    }
    throw error;
  }
  if (resolved === parse(resolved).root) {
    throw new Error("Codex working directory cannot be a filesystem root");
  }
  const configuredRoot = environment.PAPERCLIP_WORKSPACE_CWD;
  const hostHome = canonicalConfiguredPath(environment.HOME);
  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)
    ) {

View on GitHub (pinned to 01ad858492)

Solutions

Choose a neutral workspace path outside sensitive HOME subdirectories
Use the PAPERCLIP_WORKSPACE_CWD assigned workspace root for all agent sessions
Move the needed data into a workspace directory instead of running the agent in the sensitive one

Example fix

// before
workingDirectory: "~/.ssh"
// after
workingDirectory: "/workspaces/issue-123"

Defensive patterns

Strategy: validation

Validate before calling

const SENSITIVE = [".ssh", ".aws", ".gnupg", ".config"]; // mirror SENSITIVE_HOST_HOME_DIRECTORIES
const hit = home && SENSITIVE.find((d) => contains(resolve(home, d), resolve(cwd)));
if (hit) throw new Error(`workspace overlaps sensitive HOME dir ${hit}`);

Type guard

function outsideSensitiveHomeDirs(cwd: string, home?: string): boolean {
  return !SENSITIVE.some((d) => home && contains(resolve(home, d), resolve(cwd)));
}

Try / catch

try {
  validateCodexWorkingDirectory(cwd);
} catch (err) {
  if (err.message.includes("sensitive host HOME state")) {
    throw new ConfigError(`refusing to run agent in protected directory ${cwd}`);
  }
  throw err;
}

Prevention

Review workspace sources (user input, templates) for HOME-relative defaults
Keep a copy of the sensitive-directory list in test fixtures and assert workspaces avoid it
Move needed data into the workspace rather than running inside protected dirs

When it happens

Trigger: Setting the working directory to or inside a sensitive directory such as ~/.ssh, ~/.gnupg, ~/.aws, or any path listed in SENSITIVE_HOST_HOME_DIRECTORIES.

Common situations: Pointing the agent at its own credential folder to "manage keys"; configuring a workspace inside ~/.config/paperclip; copy-pasted HOME-relative defaults.

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

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