paperclipai/paperclip · error

Codex working directory cannot contain the host HOME

Error message

Codex working directory cannot contain the host HOME

What it means

To prevent leaking host credentials and config into agent sessions, the validator rejects any working directory that contains the host user's HOME directory (i.e. HOME is inside the working dir). Running the agent above HOME would let it traverse into ~/.ssh, ~/.config, etc.

Source

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

    if (!statSync(resolved).isDirectory()) {
      throw new Error("Codex working directory must be a directory");
    }
  } catch (error) {
    const code = (error as NodeJS.ErrnoException).code;
    if (code === "ENOENT") {
      throw new Error(
        "Codex working directory must exist before provider admission",
      );
    }
    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",

View on GitHub (pinned to 01ad858492)

Solutions

1. Use a dedicated workspace directory outside the HOME ancestry (e.g. /workspaces/<id>)
2. Set PAPERCLIP_WORKSPACE_CWD to an assigned workspace root when HOME must be nearby
3. Restructure the host layout so agent workspaces are siblings, not ancestors, of HOME

Example fix

// before
workingDirectory: "/home/alice"
// after
workingDirectory: "/workspaces/issue-123"

import { resolve } from "node:path";
const home = process.env.HOME;
function contains(parent: string, child: string) {
  const rel = relative(resolve(parent), resolve(child));
  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
}
if (home && contains(cwd, home)) throw new Error("workspace must not contain HOME");

function workspaceSafeFromHome(cwd: string, home?: string): boolean {
  if (!home) return true;
  return !contains(cwd, home);
}

try {
  validateCodexWorkingDirectory(cwd);
} catch (err) {
  if (err.message.includes("cannot contain the host HOME")) {
    throw new ConfigError(`workspace ${cwd} overlaps HOME; use an isolated workspace root`);
  }
  throw err;
}

When it happens

Trigger: Setting the working directory to `/home/user`, `/Users/name`, or any ancestor of $HOME (e.g. `/home`, `/` variants that survive earlier checks).

Common situations: Configuring a shared host directory as the workspace; reusing a personal machine path as the agent workspace; container setups where HOME is mounted at a shallow path.

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

• sandbox runtime asset key is not a simple path segment: ${ke
• workspace_durable_seed_invalid
• Materialized OpenCode executable has unsafe permissions
• A trusted viewer build is required for public chat reports
• Trusted viewer must not use symlinks

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