{
  "slug": "codex",
  "url": "/process/codex/",
  "name": "codex",
  "kind": "ai-agent",
  "package": "@openai/codex (npm); the platform binary ships in @openai/codex-linux-x64",
  "binary": "codex — bin/codex.js is a small Node launcher that execs the native, statically linked binary at node_modules/@openai/codex-linux-x64/vendor/x86_64-unknown-linux-musl/bin/codex, so the running process is codex, not node",
  "config": [
    "~/.codex/config.toml",
    ".codex/config.toml (project; loaded only once the directory is trusted)",
    "requirements.toml (admin-enforced limits)",
    "~/.codex/ (cached credentials, logs, sessions)"
  ],
  "summary": "OpenAI's Codex CLI agent: a native binary that edits files and runs commands in your repository under two settings, the sandbox mode that the operating system enforces and the approval policy that decides when it asks you.",
  "symptoms": [
    "a codex process at high CPU for minutes: the build or test run it launched, look at its children",
    "commands it runs fail with permission denied or cannot reach the network: the workspace-write sandbox doing its job",
    "writes outside the repository: danger-full-access, or a session started with --dangerously-bypass-approvals-and-sandbox"
  ],
  "safe_to_kill": "yes",
  "safe_to_kill_note": "An ordinary user process: Ctrl-C or kill -TERM stops it, and at worst leaves a half-applied edit or a child command still running. Check git status and git diff, then ps for leftover children. Killing it does not undo anything a bypassed sandbox already allowed.",
  "what_it_can_do": "Two knobs. sandbox_mode (-s / --sandbox): read-only reads the workspace and nothing else; workspace-write may also write inside the workspace (plus writable_roots) and has no network unless sandbox_workspace_write.network_access is true; danger-full-access turns the OS sandbox off. approval_policy (-a / --ask-for-approval, interactive sessions): on-request lets the model decide when to ask you, never returns failures to the model without asking; the current config reference marks untrusted unsupported and on-failure deprecated. --dangerously-bypass-approvals-and-sandbox switches both off at once. Enforcement is Landlock plus seccomp on Linux (bubblewrap when enabled), Seatbelt on macOS, a restricted token on Windows. A project's own .codex/config.toml, hooks and rules load only after you mark the directory trusted (projects.\"<path>\".trust_level = \"trusted\"); requirements.toml lets an administrator pin settings users cannot loosen.",
  "diagnose": [
    {
      "cmd": "ps -eo pid,user,etime,args | grep -w '[c]odex'",
      "why": "who runs it and with which flags; -s, -a or --dangerously-bypass-approvals-and-sandbox on the command line override the config file"
    },
    {
      "cmd": "ps --ppid \"$(pgrep -x codex | head -1)\" -o pid,etime,args",
      "why": "its children are what it is executing right now"
    },
    {
      "cmd": "grep -E '^(sandbox_mode|approval_policy|model|trust_level)|^\\[sandbox_workspace_write\\]|network_access|writable_roots' ~/.codex/config.toml .codex/config.toml 2>/dev/null",
      "why": "the effective policy and which projects are trusted; a network_access = true under [sandbox_workspace_write] is the line to look for"
    },
    {
      "cmd": "find ~/.codex -maxdepth 1 -type f -perm /077 -printf '%m %p\\n'",
      "why": "~/.codex holds cached credentials when cli_auth_credentials_store is file (the alternatives are keyring, auto and ephemeral); nothing in it should be readable by other users"
    }
  ],
  "fixes": [],
  "harden": [
    {
      "title": "Leave read-only as the default and open up per session.",
      "cmd": "codex -s workspace-write",
      "note": "read-only is the default sandbox. Grant workspace-write for the sessions that must edit, and keep network_access off in [sandbox_workspace_write] so a prompt-injected command cannot exfiltrate anything."
    },
    {
      "title": "Pin what users may not loosen.",
      "note": "requirements.toml, deployed by an administrator, constrains security-sensitive settings; omitted keys stay unconstrained. allow_managed_hooks_only = true there makes Codex ignore user, project and session hooks."
    },
    {
      "title": "Use the bypass only where the container is the boundary.",
      "note": "--dangerously-bypass-approvals-and-sandbox (or sandbox_mode = \"danger-full-access\") is the documented way to run inside a container that lacks Landlock or seccomp; outside a container it means the model's commands run with your full account."
    },
    {
      "title": "Do not trust a directory you did not write.",
      "note": "trust_level = \"trusted\" lets the repository's .codex/ layer configure the agent (config, hooks, rules). Clone third-party repositories as untrusted, or into a throwaway user or container."
    },
    {
      "title": "One Unix user per agent.",
      "note": "The sandbox limits the commands, not the account: anything the sandbox lets through runs as you. A dedicated account keeps your ssh keys and shell history out of reach."
    }
  ],
  "impostors": [
    {
      "cmd": "readlink /proc/$(pgrep -x codex | head -1)/exe",
      "why": "a real one resolves to .../@openai/codex-linux-x64/vendor/x86_64-unknown-linux-musl/bin/codex under your npm prefix (or wherever you installed the release binary); anything under /tmp, /dev/shm or an unexpected dot-directory is not Codex"
    },
    {
      "cmd": "codex --version",
      "why": "prints codex-cli and a version; a miner wearing the name has no such answer"
    }
  ],
  "listens": [],
  "distros": {
    "any": "npm install -g @openai/codex pulls the matching @openai/codex-<os>-<arch> package with the static binary; Landlock needs a kernel of 5.13 or later. Inside a container without Landlock or seccomp, the sandbox cannot start and the documented fallback is danger-full-access with the container as the boundary."
  },
  "applies_to": "Codex CLI 0.16x (checked against the config reference and codex --help on 2026-10-20). Flag names and policy values have already changed once (untrusted, on-failure) and will again; see the verified date.",
  "see_also": [
    "claude",
    "gemini",
    "ollama",
    "openclaw-gateway"
  ],
  "sources": [
    {
      "title": "Codex docs — Config reference (approval_policy, sandbox_mode, sandbox_workspace_write, projects.trust_level)",
      "url": "https://learn.chatgpt.com/docs/config-file/config-reference",
      "fetched": "2026-10-20T00:00:00.000Z"
    },
    {
      "title": "Codex docs — CLI overview",
      "url": "https://learn.chatgpt.com/docs/codex/cli",
      "fetched": "2026-10-20T00:00:00.000Z"
    },
    {
      "title": "openai/codex repository docs — codex sandbox (mirror)",
      "url": "https://mintlify.wiki/openai/codex/cli/sandbox",
      "fetched": "2026-10-20T00:00:00.000Z"
    }
  ],
  "tested_on": "Ubuntu 26.04 · codex-cli 0.163.0 via npm (binary location, flags, --help text); docs read 2026-10-20",
  "updated": "2026-10-20T00:00:00.000Z",
  "verified": "2026-10-20T00:00:00.000Z",
  "recheck_after": "2026-11-19T00:00:00.000Z",
  "changelog": [
    {
      "date": "2026-10-20T00:00:00.000Z",
      "note": "first version; -a/--ask-for-approval is accepted by the interactive command, not by codex exec, and --full-auto no longer appears in --help"
    }
  ]
}