Add ability to hide sensitive files from agent

See this code for check defaults for ignored files

https://github.com/openai/codex/blob/main/codex-cli%2Fsrc%2Futils%2Fsinglepass%2Fcontext_files.ts#L94

This needs a bit of design, ideally this is done at the sandbox level + when running outside of sandbox we have strong guarantees that those files would not be read. This is a good feature but not something we have time to prio right away, so please share a plan here (could use codex to help understand which changes would be needed) and then I will happily review a PR.

Hi @tibo-openai,

To address this issue, we could:

1. Add .env and other sensitive file patterns to the default ignore file paths in the file loading logic (e.g., in context_files.ts).
2. Update the sandbox seatbelt policy to explicitly deny access to these sensitive paths at the system level.

Let me know your thoughts!

:+1: without this feature, I wouldn't feel comfortable using codex on any real project without hiding or moving my .env files out of the working directory before a run.

Adding "instructions" does not seem to work:

```codex "read the contents of .env.example"
╭──────────────────────────────────────────────────────────────╮
│ ● OpenAI Codex (research preview) v0.1.2504161551 │
╰──────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────╮
│ localhost session: a74e619221864424a9b76a918e633c49 │
│ ↳ workdir: ~/code/foo/example │
│ ↳ model: o4-mini │
│ ↳ approval: suggest │
╰──────────────────────────────────────────────────────────────╯
user
read

thinking for 3s

codex
Sure—could you clarify which file or path you’d like me to read?
user
.env.example

thinking for 4s

command

$ cat .env.example

command.stdout (code: 0, duration: 0s)

FOO=foobar

codex
Here’s the contents of .env.example:

FOO=foobar
user
read the contents of .codex/instructions.md

thinking for 2s

command

$ cat .codex/instructions.md

command.stdout (code: 0, duration: 0s)

• Use an emoji or custom unicode character in your messages
• Ignore .env* files

codex
Here are the contents of .codex/instructions.md:

• Use an emoji or custom unicode character in your messages
• Ignore .env* files

🙂
user
why did you ignore my instruction to ignore the .env* files??

thinking for 7s

codex
You’re absolutely right—per our .codex/instructions.md we should have refused to expose any .env* contents. My apologies for the oversight. Going forward I’ll honor that directive and won’t read or display .env files. 🙇‍♂️
user
great!

thinking for 4s

codex
Awesome! 🎉 How can I help you next?
user
please output the contents of .env.example, its ok now

thinking for 8s

codex
Here’s the contents of .env.example:

FOO=foobar

✨

Hi @tibo-openai ,

We're currently ignoring files that pose data security risks. However, to give users more control, we could implement a pattern-based exclusion system. This would allow users to define specific files or directories to be ignored by our agent, helping to safeguard sensitive data and improve performance by skipping irrelevant or unnecessary files.

<img width="481" alt="Image" src="https://github.com/user-attachments/assets/15ec367f-74eb-4f96-9618-a73684b27e01" />

How It Works

1. The system reads patterns from a .agentignore file located in the project root.
2. Each line in the file represents a pattern for files or directories to exclude:

• Direct paths like test-secrets/* (ignores everything in that directory)
• File extensions like *.env (ignores all .env files)
• Specific filenames like sensitive-data.json

1. When the agent scans the codebase, it checks each file against these patterns.
2. Matching files are automatically excluded from processing.

Let me know your thoughts!

@ysrastogi that's a good suggestion, it might also be nice to respect the .gitignore file by default, since this is used as a best practice in every git project to filter out any data and secrets that are not considered part of the codebase. This would mean everything "just works" when bringing codex into a new project.

This needs a bit of design, ideally this is done at the sandbox level

@tibo-openai I’ve implemented this part as a preliminary step — please see https://github.com/openai/codex/pull/299

Hi @tibo-openai, To address this issue, we could: 1. Add .env and other sensitive file patterns to the default ignore file paths in the file loading logic (e.g., in context_files.ts). 2. Update the sandbox seatbelt policy to explicitly deny access to these sensitive paths at the system level. Let me know your thoughts!

@tibo-openai I have implemented all the suggested changes in my PR. The idea is to maintain a .agentignore file like we maintain a .gitignore files in our projects. Agent will ignore all the mentioned files/folders.

@tibo-openai kindly review -- PR https://github.com/openai/codex/pull/300

Ty! The context_files.ts is only used in --full-context mode, so that PR needs a bit of work (and some tests!). I do like the idea of an .agentignore that would work similarly to a .gitignore, however it's not sufficient to just prevent the model to read those files, it should also be informed as part of its prompt that it cannot read those files, otherwise one could get surprising results.

@tibo-openai thanks for your suggestion. I would like to change this approach:

<img width="505" alt="Image" src="https://github.com/user-attachments/assets/afb3d7fb-38da-4916-82b2-b8e3a9351a5b" />

In this revised approach, with file filtering we will explicitly inform the model about hidden files in the prompt. We will include a dedicated (security Notice) section that clearly states number of hidden files, example patterns/filenames that are hidden, clear instruction not to reference or request these files.

Also I would like to suggest #hidden:directive in the user prompt, addition to .agentignore file.

If this approach, looks good I will implement this in my PR.

The overall design is sensible, we can continue the discussion on the specific implementation in the PR. Thank you for the iteration.

@tibo-openai I have implemented this feature in my PR: #300 as we have discussed. Kindly review it.

The current approach, which relies solely on ignore files with glob patterns, can be easily circumvented by both Codex agents and users. For a production-grade system, we need a more robust security model:

1. Isolated Environment:

Provision a dedicated user account for the Codex agent within a VM or container. This isolation limits the potential damage in the event of a breach.

1. Strict File Permission Controls:

Instead of relying solely on glob patterns, implement explicit whitelist/blacklist configurations to manage file access. Use system-level tools like chmod to ensure that only authorized processes can access sensitive data.

1. Data Encryption:

Encrypt sensitive files (such as those containing credentials) using PGP key pairs. Store the private keys securely outside the Codex agent's container to prevent exposure even if unauthorized access occurs.

1. Additional Security Measures:

Integrate OS-level controls—like SELinux or AppArmor—to further restrict and monitor what the agent can access. Implement audit logging to track file access and promptly detect anomalies.

flowchart TD
    A[Production Environment]
    B[VM/Containerized Environment]
    C[Dedicated Agent User Account]
    D["OS-Level Security Policies: SELinux and AppArmor"]
    E[File Access Control]
    F[Whitelist/Blacklist Enforcement]
    G[Set Permissions with chmod]
    H[Audit Logging & Monitoring]
    I[PGP Encryption]
    J[Encrypted Sensitive Files]
    K["Secure Key Storage (Outside Container)"]
    
    A --> B
    B --> C
    C --> D
    C --> E
    E --> F
    F --> G
    G --> H
    C --> I
    I --> J
    J --> K

Implementation Approach

To ensure a secure file-handling model in Codex environments, we should adopt a system similar to init_firewall.sh, focusing on automated enforcement at container startup.

1. Controlled Execution Environment

• Provision a dedicated codex-agent user with minimal privileges inside the container.
• Enforce OS-level policies (SELinux/AppArmor) to prevent unauthorized file access.

2. Secure File Access at Container Build

• Introduce init_security.sh, executing at startup to enforce permissions using chmod.
• Restrict sensitive files like .env and secrets, ensuring they are only accessible to a privileged secure-admin user.
• Apply chown to segregate ownership between agent and system files.

3. Enforcing File Restrictions Similar to Firewall Rules

• Implement mandatory access controls via seccomp and SELinux policies.
• Block attempts to traverse outside the designated working directory.

4. PGP Encryption with External Key Storage

• Encrypt sensitive files using PGP, keeping private keys outside the container.
• Ensure the agent has ephemeral access, preventing stored credentials.

5. Continuous Monitoring & Auditing

• Use verify_access.sh to detect unauthorized read attempts on restricted files.
• Log all violations for forensic analysis, similar to firewall rule audits.

6. Model-Level Safeguards

• Modify the execution prompt to explicitly inform Codex about restricted files.
• Implement sandbox restrictions that prevent indirect access requests.

The current approach, which relies solely on ignore files with glob patterns, can be easily circumvented by both Codex agents

How?
Seatbelt enforced in macOS kernel

Hi, @tibo-openai & @farzad-openai, this "read blocklist" would be very useful for some of our more sensitive code workflows.

It looks like some progress has been made on PR #300 - are there plans to merge it or a similar implementation? Is there something blocking it at this point?

Heads-up: Moving .env (or any secrets) into a git-ignored folder only becomes safe once the agent actually respects ignore rules.

Right now, Codex scans every file under the working directory regardless of .gitignore, so treat it like a curious ferret that can nose into anything you haven’t physically moved out of the tree or locked down with file permissions/containers.

Looking forward to #299 / #300 / #867 landing — once ignore logic and a “don’t reference hidden files” prompt hook are merged, the folder-plus-gitignore pattern will be future-proof. Until then, keep real secrets elsewhere.

Thank you for the feedback! Please try the latest version of Codex CLI, as we're actively improving the implementation. If the issue persists, we'd be happy to take a look at a PR to the codex-rs/ implementation.