Skip to content

Commit a2c8b38

Browse files
diegocantareroIngwannu
authored andcommitted
Document Cursor exec policy and catalog troubleshooting
1 parent 5662c7e commit a2c8b38

3 files changed

Lines changed: 57 additions & 13 deletions

File tree

‎docs-site/src/content/docs/guides/codex-integration.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,33 @@ reapplies the configured name. Genuine upstream native names (e.g. `gpt-5.6-sol`
153153
"GPT-5.6-Sol") come from the pinned upstream snapshot and are never overridden by a custom display
154154
name.
155155

156+
### Catalog troubleshooting
157+
158+
If a model is missing from Codex, or the catalog order/visibility looks wrong, check in order:
159+
160+
1. **`selectedModels`** on the provider — a non-empty allowlist exposes only those ids to Codex;
161+
empty or omitted exposes all discovered models. An id not in the allowlist never reaches the
162+
catalog.
163+
2. **`disabledModels`** (top level) — hides models from both the catalog and `/v1/models`, and flips
164+
bare native GPT slugs to `visibility: "hide"`.
165+
3. **`liveModels: false` with empty `models`** — when live discovery is off and `models` is empty or
166+
omitted, opencodex exposes no routed models for that provider.
167+
4. **Cursor `GetUsableModels`** — the Cursor adapter discovers models through its protobuf
168+
`GetUsableModels` RPC, not `/models`, so a Cursor-side change can alter which ids are visible
169+
independently of other providers.
170+
5. **Cache and `ocx sync`** — live catalogs are cached for about five minutes (`modelCacheTtlMs`,
171+
default `300000`). Run `ocx sync` to force a fresh fetch and rewrite the catalog immediately.
172+
173+
:::caution[Other local writers]
174+
Catalog writes (`opencodex-catalog.json`, `config.toml`) are atomic **inside** opencodex, which only
175+
prevents half-written files when two opencodex-owned writers race. That does **not** stop another
176+
local process, file watcher, or sync agent from rewriting catalog visibility or order after opencodex
177+
has written. Codex keeps its separate `models_cache.json` and can refresh it independently, changing
178+
the visible list without rewriting `opencodex-catalog.json`. If models flip unexpectedly while the
179+
proxy is running, stop or reconfigure the competing writers, then run `ocx sync` — this is an
180+
external-writer hazard, not a confirmed opencodex defect.
181+
:::
182+
156183
## The subagent picker
157184

158185
Codex's `spawn_agent` advertises the first **5 picker-visible catalog models** after sorting by

‎docs-site/src/content/docs/reference/adapters.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -134,8 +134,9 @@ advertised effort control on those models as proof of upstream-native reasoning
134134
`cursor/auto-balance`, and `cursor/auto-intelligence` entries. Explicit levels are encoded in
135135
`requested_model.parameters` while the legacy `cursor/auto` entry retains the account/team default.
136136
- Cursor-native local filesystem/shell/network execution is denied by default. Explicit `mcpServers`
137-
and `desktopExecutor` integrations have separate opt-ins; `unsafeAllowNativeLocalExec` enables the
138-
broader built-in executor and bypasses Codex approval/sandbox semantics.
137+
and `desktopExecutor` integrations have separate opt-ins; `nativeLocalExec: "on"` enables the
138+
broader built-in executor and bypasses Codex approval/sandbox semantics, and legacy
139+
`unsafeAllowNativeLocalExec: true` remains equivalent only when `nativeLocalExec` is unset.
139140

140141
## `azure-openai` (alias: `azure`)
141142

‎docs-site/src/content/docs/reference/configuration.md‎

Lines changed: 27 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -187,7 +187,8 @@ network. Only do this on trusted networks, and always set a strong `OPENCODEX_AP
187187
| `location?` | `string` | Vertex location; environment fallback is `GOOGLE_CLOUD_LOCATION`. |
188188
| `mcpServers?` | `Record<string,CursorMcpServerConfig>` | **Cursor only.** MCP servers started over stdio or reached over Streamable HTTP; fields are listed below. |
189189
| `desktopExecutor?` | `DesktopExecutorConfig` | **Cursor only.** External computer-use/record-screen commands; fields are listed below. |
190-
| `unsafeAllowNativeLocalExec?` | `boolean` | **Cursor adapter only.** Opt-in escape hatch for Cursor server-driven local `read` / `write` / `delete` / `ls` / `grep` / `shell` / `fetch` execution. Defaults to `false` so remote Cursor messages cannot bypass Codex approval and sandbox enforcement. See [Cursor provider](#cursor-provider-adapter-cursor) below. |
190+
| `unsafeAllowNativeLocalExec?` | `boolean` | **Cursor adapter only.** Legacy compatibility boolean for the Cursor server-driven local `read` / `write` / `delete` / `ls` / `grep` / `shell` / `fetch` executor. Equivalent to `nativeLocalExec: "on"` when `nativeLocalExec` is unset; an explicit `nativeLocalExec` value always wins. Defaults to `false`. Prefer `nativeLocalExec` for new configs. See [Cursor provider](#cursor-provider-adapter-cursor) below. |
191+
| `nativeLocalExec?` | `"off" \| "codex-sandbox" \| "on"` | **Cursor adapter only.** Native local exec policy for the Cursor server-driven executor. `"off"` (default) rejects it; `"on"` is the trusted-local opt-in; `"codex-sandbox"` is accepted for backwards compatibility but is fail-closed like `"off"`. See [Cursor provider](#cursor-provider-adapter-cursor) below. |
191192

192193
For broken `openai-responses` compatibility gateways, `responsesItemIdRepair` belongs on the
193194
provider object itself, for example:
@@ -232,9 +233,17 @@ the selection is preserved on every request. They remain available when live mod
232233
`default`, just like the original `cursor/auto` entry.
233234

234235
By default, Cursor's server-driven native local tools stay **disabled**. Codex keeps using its own
235-
tools (`apply_patch`, `exec_command`, and so on) with approval and sandbox policy. Set
236-
`unsafeAllowNativeLocalExec` only for trusted local experiments where you accept that Cursor may
237-
read, write, delete, list, grep, shell, or fetch on your machine **without** Codex's approval path.
236+
tools (`apply_patch`, `exec_command`, and so on) with approval and sandbox policy. Use the
237+
`nativeLocalExec` field to choose a policy:
238+
239+
- **`"off"` (default, safest)** — rejects all Cursor server-driven local `read`, `write`, `delete`,
240+
`ls`, `grep`, `shell`, and `fetch` execution. Use this unless you have deliberately opted in.
241+
- **`"on"` (trusted-local opt-in)** — always allows Cursor-native local execution for this provider.
242+
Use it only for a trusted local experiment on a host where every data-plane caller is trusted.
243+
- **`"codex-sandbox"` (accepted, fail-closed)** — recognized for backwards compatibility, but
244+
currently behaves like `"off"`. Responses `instructions` / `system` / `developer` text is
245+
caller-controlled prose, and opencodex has no trustworthy per-request attestation that it reflects
246+
a real Codex sandbox state, so it never authorizes native local exec.
238247

239248
```json
240249
{
@@ -244,21 +253,25 @@ read, write, delete, list, grep, shell, or fetch on your machine **without** Cod
244253
"baseUrl": "https://api2.cursor.sh",
245254
"authMode": "oauth",
246255
"defaultModel": "auto",
247-
"unsafeAllowNativeLocalExec": true
256+
"nativeLocalExec": "off"
248257
}
249258
}
250259
}
251260
```
252261

253-
The flag belongs on the **provider object** (`providers.cursor`), not at the top level of
262+
The field belongs on the **provider object** (`providers.cursor`), not at the top level of
254263
`config.json`.
255264

256265
You can also set it from the [web dashboard](/opencodex/guides/web-dashboard/): **Providers →
257-
Cursor → Edit JSON**, add `"unsafeAllowNativeLocalExec": true`, save, then restart the proxy
258-
(`ocx restart` or `ocx stop` + `ocx start`).
266+
Cursor → Edit JSON**, set `"nativeLocalExec"` to `"off"`, `"on"`, or `"codex-sandbox"`, save, then
267+
restart the proxy (`ocx restart` or `ocx stop` + `ocx start`).
268+
269+
The legacy `unsafeAllowNativeLocalExec: true` boolean is still accepted and is equivalent to
270+
`nativeLocalExec: "on"` when `nativeLocalExec` is unset; an explicit `nativeLocalExec` value always
271+
wins. Prefer `nativeLocalExec` for new configs.
259272

260273
MCP, screen recording, and computer-use use separate `mcpServers` / `desktopExecutor` config and are
261-
not controlled by this flag.
274+
not controlled by this field.
262275

263276
### Cursor integration records
264277

@@ -272,8 +285,11 @@ accept `headers?: Record<string,string>`. Both forms support `enabled?: boolean`
272285
one JSON request from stdin, and must write one JSON result to stdout.
273286

274287
:::caution[Security]
275-
Leave `unsafeAllowNativeLocalExec` unset or `false` unless you explicitly want Cursor-native local
276-
execution that bypasses Codex approval and sandbox semantics.
288+
`"off"` is the safest default. The default loopback bind admits **any** local process without auth
289+
(including other local users on multi-user machines), and request text such as Codex sandbox
290+
markers never authorizes native local exec. Leave `nativeLocalExec` unset or set it to `"off"`
291+
unless you explicitly want Cursor-native local execution that bypasses Codex approval and sandbox
292+
semantics.
277293
:::
278294

279295
## OpenRouter provider routing

0 commit comments

Comments
 (0)