How to roll out Codex managed settings to a team
Set Codex approval and permission limits with requirements.toml. Test a read-only default, workspace writes and blocked full access on one machine first.
Use requirements.toml to set the approval policies and permission profiles people can use in Codex. Start with one test repo and one teammate. Give them a read-only default, let them choose workspace writes when they need to edit, and check that full access is unavailable before you roll it out.
Key takeaways
- Put enforced limits in
requirements.toml. Useconfig.tomlfor starting preferences that people can change within those limits. - The permission-profile example below requires Codex 0.138.0 or later on every client that receives it.
- In a fresh CLI session, run
/debug-configand check both the effective requirements and where they came from.
A requirements.toml example for Codex
This policy starts people in read-only mode. They can switch to workspace permissions to edit the repo. It also limits the approval policy to on-request.
default_permissions = ":read-only"
allowed_approval_policies = ["on-request"]
[allowed_permission_profiles]
":read-only" = true
":workspace" = trueThe allowlist omits :danger-full-access, so users cannot select it. With on-request, operations the current profile permits can run without a prompt. Read-only mode can still read files that the profile allows. If your rollout also needs to keep specific files out of view, configure deny-read requirements and verify support on each platform.
On older clients that use sandbox_mode, use the documented allowed_sandbox_modes requirement for those clients. Upgrade your fleet before switching to the profile example above. OpenAI managed configuration
Where to put the file
| How you manage Codex | Where to apply the requirements |
|---|---|
| A managed macOS or Linux machine | /etc/codex/requirements.toml |
| A managed Windows machine | %ProgramData%\OpenAI\Codex\requirements.toml |
| A workspace with Agent security | In the Admin Console, select the pilot policy under Agent security. Open Requirements and edit the Global TOML. Use an override for the pilot audience. |
The paths above apply to the local client. If your team also uses Codex Cloud, check the available controls for that execution environment and verify them separately. OpenAI managed configuration
Test the policy with one teammate
Use a scratch repo with a sample file and no production credentials. If you change an existing managed policy for a pilot, save the prior version so the pilot owner can restore it.
- Check the source. Open a fresh interactive Codex CLI session in the repo. Run
/debug-configand look under Requirements for the approval policy and allowed profiles. Confirm they came from the pilot policy or the managed file you deployed. - Check the default. Open
/permissionsand confirm read-only is active. Ask Codex to summarize the sample file, then attempt a scratch-file edit and verify it needs a change in permissions or approval. Leave the request unapproved for this check. - Check workspace writes. Select workspace permissions. Ask Codex to add a line to the sample file, then inspect the diff. This verifies that the allowed editing workflow still works.
- Check the limit. Confirm that
/permissionsoffers no full-access option. Repeat the test with the teammate's normal sign-in and on any other client or execution environment your team uses.
Keep the client version, policy source and results from those four checks in the rollout notes. If you change a cloud-delivered policy, start a fresh session after the client picks up the new settings and run the checks again. OpenAI configuration verification
Decide who should answer a request
Codex requirements set the limits for a session. If you also want a teammate to answer a matching request, test that as a separate step. Pick one repo and one harmless action, route the request to the intended teammate, then check that the history shows who answered. An answer made at the agent's own prompt can still bypass that routing and may leave no named Team answer.
The team approval comparison explains what Codex and other agents record. The Team setup guide shows how to connect two people and test a route.
Frequently asked questions
Where does Codex look for requirements.toml?
The system file is /etc/codex/requirements.toml on macOS and Linux and %ProgramData%\OpenAI\Codex\requirements.toml on Windows. In a workspace with Agent security, an admin can also deliver supported requirements from the Admin Console.
How can I tell whether Codex loaded my team's requirements?
Start a fresh interactive Codex CLI session in a pilot repo and run /debug-config. Under Requirements, check the values and their source. Then verify that read-only and workspace permissions behave as expected and that full access is unavailable.