Codex permissions

What Renku sets up

When you choose your Project Library, in Studio’s first-launch setup or with renku init, Renku writes one file into it: .codex/config.toml. This only happens if Renku’s Codex plugin was installed, so it does nothing for people who don’t use Codex.

Codex reads that file only when it works in your Project Library. Everywhere else, Codex keeps using your own settings. Renku never edits ~/.codex/config.toml.

Installed Renku before this was added? Run this once in Terminal. It shows the file, asks before writing it, and checks that Codex accepts it:

renku codex permissions set

What it allows

The file starts from Codex’s standard workspace rules and adds only what Renku needs:

• Your Project Library: read and write, so Renku can save films, media and generated files. This is the folder Codex is working in.
• Renku’s settings folder (~/.config/renku): read only. Your provider API keys are kept here; Codex never changes them.
• Renku’s state folder (~/.local/state/renku): read and write. Renku keeps saved provider prices and model information, the current project and the model list here.
• Network access: so Renku can reach the generation providers and tell Studio, on this computer, to refresh.

Everything else stays protected: Codex still can’t write to your Documents, other projects or system folders. This is the file Renku writes, with your own folder paths:

# Managed by Renku (`renku codex permissions`).
# Codex applies these permissions only when it works in this folder.
# Renku refreshes this file on updates; delete the first line to keep your own edits.
default_permissions = "renku-studio"

[permissions.renku-studio]
description = "Renku: films, settings, state and Studio."
extends = ":workspace"

[permissions.renku-studio.filesystem]
"/Users/you/.config/renku" = "read"
"/Users/you/.local/state/renku" = "write"

[permissions.renku-studio.network]
enabled = true
allow_local_binding = true

On Windows, Renku’s settings folder is %LOCALAPPDATA%\Renku\Studio and its state folder is %LOCALAPPDATA%\Renku\Studio\State.

Trust the folder in Codex

This is the one step Renku can’t do for you. Codex only reads a folder’s settings once you trust that folder.

• Open Codex in your Project Library, the folder that holds all your films. Studio shows its path at the top of the Projects page.
• When Codex asks whether to trust the folder, choose to trust it.
• Start a new Codex thread there for Renku work. Threads that were already open keep their old permissions.

Open Codex at the Project Library rather than inside one film’s folder. A film folder doesn’t use the Project Library’s settings, so commands there would ask for approval again.

Check, refresh or remove

See whether the permissions are in place, and whether Codex accepts them:

renku codex permissions status

“Renku can save its data” means everything works. “Refused” usually means the folder isn’t trusted in Codex yet.

renku update keeps the file current. To take the permissions away again, run the command below. It deletes only the file Renku wrote.

renku codex permissions remove

Agents may check the status, but only you run set or remove.

If you have your own Codex settings there

If your Project Library already has a .codex/config.toml that you wrote, Renku leaves it unchanged and says so. To keep your file and still let Codex run Renku, copy the [permissions.renku-studio] sections and the default_permissions line shown above into it.

Earlier versions of these instructions asked you to add the profile to your personal ~/.codex/config.toml and make it your default. You no longer need that: you can put your personal default_permissions back to what you had before.

Troubleshooting

• An approval prompt, or “Automatic approval review blocked”, for a renku command: the command left the sandbox. Check that you opened Codex in the Project Library, trusted it, and started a new thread. Then run renku codex permissions status.
• ENGINE_METADATA_CACHE_UNWRITABLE: Renku couldn’t save provider information in its state folder. The same checks apply; the message names the folder.
• CLI026: the change was made, but Studio wasn’t told to refresh. Check that Studio is running, then refresh it. Don’t run the command again.

For a tighter setup that allows only the providers you use, see the detailed Codex permissions guide.