Start the upstream Codex CLI against an Azure AI Foundry deployment, choose the model and reasoning effort, and control the sandbox and loopback port.
pks codex run [ARGS] [options]$ pks codexLaunch on the default Foundry deployment
$ pks codex run --model gpt-5-codex --reasoning-effort highExplicit deployment plus reasoning effort
$ pks codex run --safeKeep Codex approval prompts and sandbox enabled
$ pks codex run --print-envPrint the launch command instead of running codex
Start a Codex session that bills through Azure AI Foundry: pks starts the loopback passthrough, resolves a deployment, and execs the real codex binary against it. Bare pks codex and pks codex run are the same command — run is the explicit form, and the one to use when you also pass native Codex arguments.
pks foundry init must have completed, with a resource endpoint selected.npm i -g @openai/codex. Without it the command exits 127 with an install hint.gpt-5-codex on port 8788.pks codex
The passthrough binds a loopback port, and the Codex CLI opens against the resolved Foundry deployment. From here the interface is entirely Codex's own.
pks codex run --model gpt-5.6-sol --reasoning-effort high
The deployment resolves in this order:
-m, --model on the command line.Deployment in ~/.pks-cli/codex.json, written by pks codex init.gpt-5-codex.By default pks appends --dangerously-bypass-approvals-and-sandbox to the Codex invocation, on the assumption that you run in an already-isolated environment such as a devcontainer or a disposable VM.
pks codex run --safe
--safe keeps Codex's own approval prompts and sandboxing in place. Use it whenever the session runs directly on a machine you care about.
Anything after the pks flags is forwarded to the real codex binary unchanged. Use the explicit run form so it stays unambiguous which flags bind to pks and which are forwarded.
pks codex run --model gpt-5-codex -- --help
pks codex --print-env
The passthrough runs in the foreground and prints the launch command instead of starting Codex. The printed command names the resolved deployment and the loopback port actually in use, which is the fastest way to confirm the resolution order landed where you expected.
| Flag | Default | Description |
|---|---|---|
-m, --model <name> | Configured deployment, else gpt-5-codex | Foundry deployment name for this run. |
-e, --reasoning-effort <level> | Configured value, else medium | Reasoning effort: none, low, medium, high, xhigh, or default (omits the -c model_reasoning_effort override and lets Codex use its own built-in default). |
-p, --port <port> | Configured value, else 8788 | Loopback port for the passthrough. |
--print-env | false | Run the passthrough in the foreground and print the launch command instead of starting Codex. |
--safe | false | Keep Codex approval prompts and sandbox enabled. |
The positional ARGS are passed through to the underlying codex command.
Exit code 127 with an install hint. The codex binary is not on PATH. Install @openai/codex globally, or use --print-env and launch Codex yourself with the printed command.
Exit code 1 pointing at pks foundry init. Authentication or the resource endpoint is missing. Re-run pks foundry init.
A yellow warning about the port. The requested port, 8788 by default, is already bound — often by a stale passthrough. pks falls back to a free port automatically instead of failing.
The session dies with no visible error. Auth failures, non-2xx upstream responses, and response.failed events are appended to ~/.pks-cli/codex-passthrough-failures.log rather than printed in full. Read that file first.
Foundry rejects a request mentioning tool namespaces. pks launches Codex with collaboration_modes, apps, multi_agent_v2, and multi_agent disabled, and the passthrough strips collaboration-namespaced tool entries, because Foundry rejects OpenAI-internal encrypted tool namespaces. A newer Codex feature outside that list can hit the same wall.