//DOCS Codex

Launch Codex through Punk

punk launch codex keeps Codex as the coding-agent harness while routing every model step through Punk's Responses API runtime.

Codex continues to own the terminal or desktop interface, repository access, instruction and skill discovery, local tool execution, approvals, and sandbox. Punk owns model routing, Chorus coordination, policy and DLP checks, tracing, cost accounting, route explanations, and safe optimization.

This is a model-provider integration, not an MCP integration.

Support matrix

The minimum supported Codex CLI version is 0.134.0. The pinned compatibility baseline is Codex source commit 20dafe201d91d4405eef05ecd1db0257f13a9ac8; the launcher catalog was validated with Codex CLI 0.142.5 on 2026-07-25. A dedicated launcher workflow exercises the CLI contract on macOS, Linux, and Windows; its macOS lane also exercises the guarded desktop-process path. Run the doctor after either Codex or Punk is upgraded.

Prerequisites

Install Codex so codex --version works. For the hosted Punk gateway, create a tenant API key and export it only in the launch environment:

export PUNK_API_KEY="pk_..."
punk launch codex

The default gateway is https://app.punktechnologies.com. Operators can select another authorized gateway with PUNK_GATEWAY_URL or --gateway-url.

CLI launch

The default model is punk/chorus:

punk launch codex
punk launch codex --model punk/chorus
punk launch codex -- --full-auto
punk launch codex exec -- "fix the failing tests"
punk launch codex resume --last

Punk-owned flags must precede the Codex subcommand or -- boundary. Arguments after that boundary are passed to Codex unchanged. Punk rejects pass-through --model, --config, and --profile overrides, their short aliases, local-provider mode, and remote app-server mode because they could escape the managed provider. The launcher prepends its own highest-precedence model, provider, endpoint, credential-variable, catalog, and attribution settings; the original Codex arguments remain unchanged after that managed prefix.

To use an alternate credential without printing or persisting it:

punk launch codex --api-key env:TEAM_PUNK_API_KEY

Attribution dimensions can be set explicitly:

punk launch codex \
  --app engineering \
  --agent codex-cli \
  --subject user-123

The subject is passed through an environment-backed header and is not written into the generated configuration.

Desktop launch

On macOS:

punk launch codex --surface app

The launcher resolves an installed Codex-branded ChatGPT.app or Codex.app, validates its com.openai.codex bundle identifier, creates the managed configuration, verifies the gateway, confirms no Codex Desktop process is already running, and then starts the app executable as a direct child with the isolated environment. It supplies the current directory through Codex's documented codex://threads/new?path=... workspace link.

For a nonstandard installation:

punk launch codex --surface app --codex-app "/path/to/Codex.app"

or:

export CODEX_APP_PATH="/path/to/Codex.app"
punk launch codex --surface app

An existing desktop process cannot inherit a newly supplied CODEX_HOME or credential. Punk therefore fails closed when Codex Desktop is already running. Quit the app completely, including any background process, then launch it again through Punk. The launcher does not use open, codex app, or another mechanism that could silently reuse the wrong process.

Codex subcommands and pass-through arguments apply only to the CLI surface. Use --cwd to select the desktop workspace.

Trusted project .codex/config.toml files normally outrank user configuration. The CLI surface neutralizes model-provider changes with higher-precedence flags. The desktop executable has no equivalent documented override channel, so the desktop launcher fails closed if a project config from the workspace to its repository root defines model, model_provider, model_providers, model_catalog_json, or openai_base_url. Remove only those provider overrides or use the CLI surface; other project Codex settings remain supported.

Isolated Codex state

Punk never modifies the user's normal ~/.codex directory or a repository's .codex directory. It creates a separate, versioned CODEX_HOME using this precedence:

Override it for an isolated team or test profile:

punk launch codex --codex-home "/private/path/punk-codex"

The launcher manages:

• config.toml, containing the Punk Responses provider but no credential;
• punk-models.json, containing Codex model and tool capability metadata;
• punk-launcher-telemetry.jsonl and its bounded .1 segment, containing privacy-safe launch

outcomes;

• .punk-launch.lock while the launched Codex process owns that home.

On platforms with POSIX permissions, the directory is 0700 and managed files are 0600. Writes are atomic. Files without Punk's managed marker are never replaced. Sessions and other safe Codex state in the isolated home are retained across launches.

The current managed-file schema is version 2. When Punk encounters an older or unrecognized file carrying its managed marker, it writes an owner-only sibling named <file>.punk-backup-<timestamp>-<id> before atomically installing the current version. These recoverable backups are never loaded by Codex and may be moved to Trash after the upgraded launch has been verified. A file without Punk's marker remains untouched and causes launch to fail.

Actual launch attempts append owner-only telemetry to punk-launcher-telemetry.jsonl in this managed home. Each JSON line has a strict allowlist: schema, timestamp, event, CLI or desktop surface, operating-system platform, and normalized Codex version. Events cover launch attempt, terminal success or failure, compatibility-probe pass or failure, and unsupported versions. The files never include credentials, authorization or attribution headers, gateway or filesystem paths, prompts, arguments, request bodies, or provider error text. A separate private lock serializes writers across processes. At 32 KiB the active file rotates to a 32 KiB .1 segment, preserving the most recent complete events while bounding the total to approximately 64 KiB. --dry-run, --doctor, and --print-config do not create or update telemetry.

The generated provider uses a base URL ending in exactly /v1, wire_api = "responses", env_key = "PUNK_API_KEY", and supports_websockets = false.

Versioned CLI config, desktop config, and model-catalog compatibility fixtures live in fixtures/codex-launcher. The catalog advertises only capabilities covered by the pinned contract: buffered and SSE Responses, function tools, custom apply_patch, parallel calls, reasoning summaries, and text input.

Diagnostics

Preview without starting processes or writing files:

punk launch codex --dry-run

The dry run resolves the binary or app, version, model, gateway, managed home, health, Responses probe, and whether a local development gateway would be started. Secrets are printed only as <redacted>.

Run the compatibility doctor:

punk launch codex --doctor
punk launch codex --surface app --doctor

A passing doctor confirms:

• the Codex CLI is supported;
• the declared CLI and desktop platform policy;
• the enabled provider capabilities and disabled WebSocket transport;
• the desktop target is fresh-process ready when requested;
• the gateway health contract is recognized;
• POST /v1/responses recognizes the non-mutating invalid-request probe;
• the managed home is empty, recognized, or safely creatable.

Preview the generated provider and catalog:

punk launch codex --print-config

This output contains the environment variable name but never its value.

Gateway lifecycle

For a hosted gateway, the default is --start-gateway never.

For a local Punk development URL, the default is --start-gateway auto: a healthy gateway is reused; an unreachable local gateway is started from the Punk checkout; a reachable non-Punk server is rejected. Use --punk-cwd when the checkout is elsewhere.

The launcher stops only a gateway process that it started. Signals are forwarded to Codex, the Codex exit code is returned, and the managed lock is released on normal or handled-error exit.

Tools, approvals, and policy

Punk can return declared function calls such as shell_command and custom calls such as apply_patch. It does not execute those calls.

The sequence is:

1. Punk evaluates the model step and proposed call under runtime policy.
2. Punk returns an allowed typed call to Codex.
3. Codex independently applies its local approval and sandbox rules.
4. Codex executes locally only when its own rules allow.
5. A later Responses request carries the function or custom-tool output back through Punk.

Tool declaration is not tool execution. A powerful declared tool is not blocked merely because it exists, but a proposed invocation can be governed using its actual arguments.

Punk never adds --dangerously-bypass-approvals-and-sandbox. That setting is used only when the operator explicitly passes it to the Codex CLI after the -- boundary.

Routes and evidence

Use --model punk/chorus for the governed multi-model route. A configured direct provider model can be selected with --model <model-id>. Both use the same Responses endpoint and preserve Codex's local execution boundary.

Inspect the resulting run in the Punk dashboard to review:

• selected route and provider;
• policy and DLP result;
• proposed tool calls;
• token and cost accounting;
• cache or artifact eligibility;
• fail-open reason when a derived route was unsafe;
• replay, shadow, and promotion evidence where applicable.

A proposed tool call is not evidence that the local action succeeded. Success is established only after Codex supplies the corresponding tool output on a later turn.

Upgrade and rollback

Before upgrading Codex:

1. Record the current codex --version.
2. Upgrade Codex using its supported installation method.
3. Run punk launch codex --doctor.
4. Run one non-destructive codex exec prompt through Punk.
5. Confirm the run and route explanation in the dashboard.

The next successful launch atomically refreshes Punk-managed configuration and catalog files while retaining isolated sessions. An unsupported or unparseable Codex version fails before launch.

To roll back the integration, quit the Punk-launched Codex process and start codex normally. The user's standard Codex state was never changed. To roll back Codex itself, reinstall the previously approved Codex version and rerun the Punk doctor.

Removing Punk-managed Codex state

Quit every Codex process launched through Punk and confirm no launch is active. Then move only the resolved managed home shown by --dry-run or --doctor to the operating system Trash. Do not remove the normal ~/.codex directory.

If PUNK_CODEX_HOME or --codex-home was used, remove that exact resolved directory instead of the default. Moving the directory to Trash removes Punk-managed config, catalog, sessions, and other state stored inside it, including launcher telemetry, and remains recoverable until Trash is emptied. To retain sessions while clearing only launch evidence, quit all Punk-launched Codex processes and move punk-launcher-telemetry.jsonl plus punk-launcher-telemetry.jsonl.1 to Trash; the launcher recreates the active file on the next actual launch.

Troubleshooting

New optional Responses fields can be preserved live-only, but a newly required or unsupported item may cause a safe provider failure until the compatibility contract is updated. Run the doctor and consult the current Punk release notes after upgrades. Image input is not advertised by the launcher catalog until a real-Codex image scenario is part of the release matrix.