### Install and Start WSL Source: https://learn.chatgpt.com/docs/windows/wsl Commands to install the default Linux distribution and initiate a shell session. ```powershell # Install default Linux distribution (like Ubuntu) wsl --install # Start a shell inside Windows Subsystem for Linux wsl ``` -------------------------------- ### Setup Windows sandbox with windowsSandbox/setupStart Source: https://learn.chatgpt.com/docs/app-server Triggers asynchronous Windows sandbox setup. Includes the request and the subsequent completion notification. ```json { "method": "windowsSandbox/setupStart", "id": 53, "params": { "mode": "elevated" } } { "id": 53, "result": { "started": true } } ``` ```json { "method": "windowsSandbox/setupCompleted", "params": { "mode": "elevated", "success": true, "error": null } } ``` -------------------------------- ### windowsSandbox/setupStart Source: https://learn.chatgpt.com/docs/app-server Triggers the Windows sandbox setup process asynchronously. ```APIDOC ## windowsSandbox/setupStart ### Description Triggers sandbox setup asynchronously for custom Windows clients. ### Parameters - **mode** (string) - Required - The setup mode, either 'elevated' or 'unelevated'. ``` -------------------------------- ### Install project dependencies Source: https://learn.chatgpt.com/docs/mcp-server Sets up a Python virtual environment and installs the required OpenAI Agents SDK packages. ```bash python -m venv .venv source .venv/bin/activate pip install --upgrade openai openai-agents python-dotenv ``` -------------------------------- ### Start development server Source: https://learn.chatgpt.com/docs/prompting Run the Vite development server. ```bash npm run dev ``` -------------------------------- ### Run unattended installer Source: https://learn.chatgpt.com/docs/config-file/environment-variables Use these commands to execute the installer without interactive prompts. ```bash curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh ``` ```powershell $env:CODEX_NON_INTERACTIVE=1; irm https://chatgpt.com/codex/install.ps1 | iex ``` -------------------------------- ### Configure custom setup script Source: https://learn.chatgpt.com/docs/environments/cloud-environment Use a custom Bash script to install specific tools or dependencies that are not handled by automatic package manager detection. ```bash # Install type checker pip install pyright # Install dependencies poetry install --with test pnpm install ``` -------------------------------- ### plugin/install Source: https://learn.chatgpt.com/docs/app-server Install a plugin from a marketplace. ```APIDOC ## plugin/install ### Description Install a plugin from a marketplace path or remote marketplace name. Note: This method is currently under development and should not be used in production clients. ``` -------------------------------- ### Install ChatGPT via Winget Source: https://learn.chatgpt.com/docs/windows/windows-app Use the Windows Package Manager to install the ChatGPT desktop application from the Microsoft Store. ```powershell winget install Codex -s msstore ``` -------------------------------- ### Install Developer Tools via Winget Source: https://learn.chatgpt.com/docs/windows/windows-app Use these commands in the integrated terminal to install Git, Node.js, Python, .NET SDK, and GitHub CLI. ```powershell winget install --id Git.Git winget install --id OpenJS.NodeJS.LTS winget install --id Python.Python.3.14 winget install --id Microsoft.DotNet.SDK.10 winget install --id GitHub.cli ``` -------------------------------- ### Install Codex SDK for Python Source: https://learn.chatgpt.com/docs/codex-sdk Install the Python SDK via pip. Use --pre for prerelease builds if necessary. ```bash pip install openai-codex ``` -------------------------------- ### Configure Sandbox Policies Source: https://learn.chatgpt.com/docs/app-server Examples of read-only and workspace-write sandbox policy configurations. ```json { "type": "readOnly", "access": { "type": "fullAccess" } } ``` ```json { "type": "workspaceWrite", "writableRoots": ["/Users/me/project"], "readOnlyAccess": { "type": "restricted", "includePlatformDefaults": true, "readableRoots": ["/Users/me/shared-read-only"] }, "networkAccess": false } ``` -------------------------------- ### Implement Node.js Client Integration Source: https://learn.chatgpt.com/docs/app-server Example of spawning the app-server process and communicating via stdio in Node.js. ```ts const proc = spawn("codex", ["app-server"], { stdio: ["pipe", "pipe", "inherit"], }); const rl = readline.createInterface({ input: proc.stdout }); const send = (message: unknown) => { proc.stdin.write(`${JSON.stringify(message)}\n`); }; let threadId: string | null = null; rl.on("line", (line) => { const msg = JSON.parse(line) as any; console.log("server:", msg); if (msg.id === 1 && msg.result?.thread?.id && !threadId) { threadId = msg.result.thread.id; send({ method: "turn/start", id: 2, params: { threadId, input: [{ type: "text", text: "Summarize this repo." }], }, }); } }); send({ method: "initialize", id: 0, params: { clientInfo: { name: "my_product", title: "My Product", version: "0.1.0", }, }, }); send({ method: "initialized", params: {} }); send({ method: "thread/start", id: 1, params: { model: "gpt-5.4" } }); ``` -------------------------------- ### Launch Codex App Server with stdio Source: https://learn.chatgpt.com/docs/developer-commands?surface=app Starts the server using the default JSONL-over-stdio transport. ```bash codex app-server --listen stdio:// ``` ```bash codex app-server --stdio ``` -------------------------------- ### Start WebSocket Listener Source: https://learn.chatgpt.com/docs/app-server Initializes the app-server to listen for incoming connections on a specified WebSocket address. ```bash codex app-server --listen ws://127.0.0.1:4500 ``` -------------------------------- ### GET /readyz Source: https://learn.chatgpt.com/docs/app-server Checks if the server is ready to accept new connections. ```APIDOC ## GET /readyz ### Description Returns 200 OK once the listener accepts new connections. ### Method GET ### Endpoint /readyz ### Response #### Success Response (200) - **Status** (string) - OK ``` -------------------------------- ### codex://plugins/install/ Source: https://learn.chatgpt.com/docs/reference/commands Opens the install flow for a plugin from a known marketplace. ```APIDOC ## codex://plugins/install/ ### Description Opens the plugin detail or install flow for a plugin from a marketplace that Codex recognizes. ### Parameters #### Path Parameters - **plugin-name** (string) - Required - The name of the plugin to install. #### Query Parameters - **marketplace** (string) - Required - Identifies the marketplace. Use 'openai-curated' for OpenAI-curated plugins. ``` -------------------------------- ### Example configuration for an MCP server Source: https://learn.chatgpt.com/docs/extend/mcp Demonstrates a basic STDIO server configuration using npx and custom environment variables. ```toml [mcp_servers.context7] command = "npx" args = ["-y", "@upstash/context7-mcp"] env_vars = ["LOCAL_TOKEN"] [mcp_servers.context7.env] MY_ENV_VAR = "MY_ENV_VALUE" ``` -------------------------------- ### Configure TypeScript project setup Source: https://learn.chatgpt.com/docs/environments/local-environment Run these commands automatically when Codex creates a new worktree to ensure dependencies are installed and the project is built. ```bash npm install npm run build ``` -------------------------------- ### Codex Configuration Template Source: https://learn.chatgpt.com/docs/config-file/config-sample Use this TOML configuration as a starting point for ~/.codex/config.toml or project-scoped configurations. Root keys must be defined before tables, and optional settings are provided as commented-out examples. ```toml # Codex example configuration (config.toml) # # This file lists the main keys Codex reads from config.toml, along with default # behaviors, recommended examples, and concise explanations. Adjust as needed. # # Notes # - Root keys must appear before tables in TOML. # - Optional keys that default to "unset" are shown commented out with notes. # - MCP servers, profile files, and model providers are examples; remove or edit. ################################################################################ # Core Model Selection ################################################################################ # Primary model used by Codex. Recommended example for most users: "gpt-5.6". model = "gpt-5.6" # Communication style for supported models. Allowed values: none | friendly | pragmatic # personality = "pragmatic" # Optional model override for /review. Default: unset (uses current session model). # review_model = "gpt-5.6" # Provider id selected from [model_providers]. Default: "openai". model_provider = "openai" # Default OSS provider for --oss sessions. When unset, Codex prompts. Default: unset. # oss_provider = "ollama" # Preferred service tier. Built-in examples: fast | flex; model catalogs can add more. # service_tier = "flex" # Optional manual model metadata. When unset, Codex uses model or preset defaults. # model_context_window = 128000 # tokens; default: auto for model # model_auto_compact_token_limit = 64000 # tokens; unset uses model defaults # model_auto_compact_token_limit_scope = "total" # total | body_after_prefix; default: total # tool_output_token_limit = 12000 # tokens stored per tool output # model_catalog_json = "/absolute/path/to/models.json" # optional startup-only model catalog override # background_terminal_max_timeout = 300000 # ms; max empty write_stdin poll window (default 5m) # log_dir = "/absolute/path/to/codex-logs" # log directory; setting explicitly enables codex-tui.log; default: "$CODEX_HOME/log" # sqlite_home = "/absolute/path/to/codex-state" # optional SQLite-backed runtime state directory ################################################################################ # Reasoning & Verbosity (Responses API capable models) ################################################################################ # Reasoning effort: minimal | low | medium | high | xhigh # model_reasoning_effort = "medium" # Optional override used when Codex runs in plan mode: none | minimal | low | medium | high | xhigh # plan_mode_reasoning_effort = "high" # Reasoning summary: auto | concise | detailed | none # model_reasoning_summary = "auto" # Text verbosity for GPT-5 family (Responses API): low | medium | high # model_verbosity = "medium" # Force enable or disable reasoning summaries for current model. # model_supports_reasoning_summaries = true ################################################################################ # Instruction Overrides ################################################################################ # Additional user instructions are injected before AGENTS.md. Default: unset. # developer_instructions = "" # Inline override for the history compaction prompt. Default: unset. # compact_prompt = "" # Override built-in base instructions with a file path. Default: unset. # model_instructions_file = "/absolute/or/relative/path/to/instructions.txt" # Load the compact prompt override from a file. Default: unset. # experimental_compact_prompt_file = "/absolute/or/relative/path/to/compact_prompt.txt" ################################################################################ # Notifications ################################################################################ # External notifier program (argv array). When unset: disabled. # notify = ["notify-send", "Codex"] ################################################################################ # Approval & Sandbox ################################################################################ # When to ask for command approval: ``` -------------------------------- ### Install bubblewrap on Linux Source: https://learn.chatgpt.com/docs/sandboxing Install the bubblewrap package using the system's package manager. ```bash sudo apt install bubblewrap ``` ```bash sudo dnf install bubblewrap ``` -------------------------------- ### Install local plugin to repository Source: https://learn.chatgpt.com/docs/build-plugins Commands to create the plugin directory and copy the plugin files into the repository root. ```bash mkdir -p ./plugins cp -R /absolute/path/to/my-plugin ./plugins/my-plugin ``` -------------------------------- ### Create a plugin directory Source: https://learn.chatgpt.com/docs/build-plugins Initialize the folder structure for a new plugin. ```bash mkdir -p my-first-plugin/.codex-plugin ``` -------------------------------- ### Install Codex SDK for TypeScript Source: https://learn.chatgpt.com/docs/codex-sdk Use npm to install the required package for the TypeScript SDK. ```bash npm install @openai/codex-sdk ``` -------------------------------- ### Prompt injection example request Source: https://learn.chatgpt.com/docs/cloud/internet-access Example of a user prompt that directs an agent to a specific GitHub issue. ```text Fix this issue: https://github.com/org/repo/issues/123 ``` -------------------------------- ### Start Dev Container via CLI Source: https://learn.chatgpt.com/docs/agent-approvals-security Use the devcontainer CLI to initialize the environment using the secure configuration file. ```bash devcontainer up --workspace-folder . --config .devcontainer/devcontainer.secure.json ``` -------------------------------- ### Install and Run Codex in WSL Source: https://learn.chatgpt.com/docs/windows/wsl Download and execute the Codex CLI installation script within the Linux environment. ```bash # Install and run Codex in WSL curl -fsSL https://chatgpt.com/codex/install.sh | sh codex ``` -------------------------------- ### Initialize Project Directory Source: https://learn.chatgpt.com/docs/windows/wsl Create a workspace directory in the Linux home path to ensure optimal I/O performance. ```bash mkdir -p ~/code && cd ~/code git clone https://github.com/your/repo.git cd repo ``` -------------------------------- ### Explain Codebase via CLI Source: https://learn.chatgpt.com/docs/prompting Use file references with @ to provide context for protocol or schema analysis. ```text I need to understand the protocol used by this service. Read @foo.ts @schema.ts and explain the schema and request/response flow. Focus on required vs optional fields and backward compatibility rules. ``` -------------------------------- ### Configure MCP Servers Source: https://learn.chatgpt.com/docs/config-file/config-sample Examples for setting up MCP servers using either STDIO or HTTP transport protocols. ```toml [mcp_servers.docs] enabled = true # optional; default true required = true # optional; fail startup/resume if this server cannot initialize command = "docs-server" # required args = ["--port", "4000"] # optional env = { "API_KEY" = "value" } # optional key/value pairs copied as-is env_vars = ["ANOTHER_SECRET"] # optional: forward local parent env vars env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }] cwd = "/path/to/server" # optional working directory override experimental_environment = "remote" # experimental: run stdio via a remote executor startup_timeout_sec = 10.0 # optional; default 10.0 seconds # startup_timeout_ms = 10000 # optional alias for startup timeout (milliseconds) tool_timeout_sec = 60.0 # optional; default 60.0 seconds enabled_tools = ["search", "summarize"] # optional allow-list disabled_tools = ["slow-tool"] # optional deny-list (applied after allow-list) scopes = ["read:docs"] # optional OAuth scopes oauth_resource = "https://docs.example.com/" # optional OAuth resource ``` ```toml [mcp_servers.github] enabled = true # optional; default true required = true # optional; fail startup/resume if this server cannot initialize url = "https://github-mcp.example.com/mcp" # required bearer_token_env_var = "GITHUB_TOKEN" # optional; Authorization: Bearer http_headers = { "X-Example" = "value" } # optional static headers env_http_headers = { "X-Auth" = "AUTH_ENV" } # optional headers populated from env vars startup_timeout_sec = 10.0 # optional tool_timeout_sec = 60.0 # optional enabled_tools = ["list_issues"] # optional allow-list disabled_tools = ["delete_issue"] # optional deny-list scopes = ["repo"] # optional OAuth scopes ``` -------------------------------- ### PowerShell Execution Policy Error Example Source: https://learn.chatgpt.com/docs/windows/windows-app Example of an error message encountered when PowerShell blocks script execution. ```text npm.ps1 cannot be loaded because running scripts is disabled on this system. ``` -------------------------------- ### Create a SKILL.md file Source: https://learn.chatgpt.com/docs/customization/overview A sample SKILL.md file containing frontmatter metadata and instructional content for the agent. ```markdown --- name: commit description: Stage and commit changes in semantic groups. Use when the user wants to commit, organize commits, or clean up a branch before pushing. --- 1. Do not run `git add .`. Stage files in logical groups by purpose. 2. Group into separate commits: feat → test → docs → refactor → chore. 3. Write concise commit messages that match the change scope. 4. Keep each commit focused and reviewable. ``` -------------------------------- ### Start a Turn with Skill Invocation Source: https://learn.chatgpt.com/docs/app-server Starts a turn that explicitly invokes a skill by providing the skill name and path. ```json { "method": "turn/start", "id": 33, "params": { "threadId": "thr_123", "input": [ { "type": "text", "text": "$skill-creator Add a new skill for triaging flaky CI and include step-by-step usage." }, { "type": "skill", "name": "skill-creator", "path": "/Users/me/.codex/skills/skill-creator/SKILL.md" } ] } } { "id": 33, "result": { "turn": { "id": "turn_457", "status": "inProgress", "items": [], "error": null } } } ``` -------------------------------- ### Launch with Experimental Features Source: https://learn.chatgpt.com/docs/developer-commands?surface=app Includes gated fields and methods when generating schemas for client bindings. ```bash codex app-server --experimental ``` -------------------------------- ### account/login/start (ChatGPT Device-Code Flow) Source: https://learn.chatgpt.com/docs/app-server Initiates a device-code login flow for ChatGPT. ```APIDOC ## account/login/start (ChatGPT Device-Code Flow) ### Description Starts the device-code login flow, providing a verification URL and user code for the user to authenticate externally. ### Parameters - **type** (string) - Required - Must be "chatgptDeviceCode". ### Request Example { "method": "account/login/start", "id": 4, "params": { "type": "chatgptDeviceCode" } } ``` -------------------------------- ### Install local plugin to personal directory Source: https://learn.chatgpt.com/docs/build-plugins Commands to create the personal plugin directory and copy the plugin files into the user's home directory. ```bash mkdir -p ~/.codex/plugins cp -R /absolute/path/to/my-plugin ~/.codex/plugins/my-plugin ``` -------------------------------- ### Configure Project Documentation and Root Source: https://learn.chatgpt.com/docs/config-schema.json Settings for project documentation fallback files and root directory detection. ```json "project_doc_fallback_filenames": { "default": [], "description": "Ordered list of fallback filenames to look for when AGENTS.md is missing.", "items": { "type": "string" }, "type": "array" }, "project_doc_max_bytes": { "default": 32768, "description": "Maximum number of bytes to include from an AGENTS.md project doc file.", "format": "uint", "minimum": 0.0, "type": "integer" }, "project_root_markers": { "default": null, "description": "Markers used to detect the project root when searching parent directories for `.codex` folders. Defaults to [".git"] when unset.", "items": { "type": "string" }, "type": "array" } ``` -------------------------------- ### Install Visual Studio Build Tools via winget Source: https://learn.chatgpt.com/docs/windows/windows-sandbox Use this command to install the required C++ build tools if the IDE extension is unresponsive due to missing dependencies. ```powershell winget install --id Microsoft.VisualStudio.2022.BuildTools -e ``` -------------------------------- ### codex plugin remove Source: https://learn.chatgpt.com/docs/developer-commands?surface=cli Remove an installed plugin. ```APIDOC ## codex plugin remove ### Description Remove an installed plugin from local config and cache. ### Parameters - **plugin[@marketplace]** (string) - Required - The plugin identifier to remove. - **--marketplace, -m** (string) - Optional - The name of the marketplace. - **--json** (flag) - Optional - Enables automation-friendly output. ``` -------------------------------- ### codex plugin list Source: https://learn.chatgpt.com/docs/developer-commands?surface=cli List installed plugins. ```APIDOC ## codex plugin list ### Description List installed plugins. With --json, output has installed and available arrays; --available includes uninstalled marketplace plugins and requires --json. ### Parameters - **--marketplace, -m** (string) - Optional - The name of the marketplace. - **--available** (flag) - Optional - Includes uninstalled marketplace plugins (requires --json). - **--json** (flag) - Optional - Enables automation-friendly output. ``` -------------------------------- ### account/login/start (API Key) Source: https://learn.chatgpt.com/docs/app-server Initiates a login session using an API key. ```APIDOC ## account/login/start (API Key) ### Description Logs the user in using a provided API key. ### Parameters - **type** (string) - Required - Must be "apiKey". - **apiKey** (string) - Required - The API key string. ### Request Example { "method": "account/login/start", "id": 2, "params": { "type": "apiKey", "apiKey": "sk-..." } } ``` -------------------------------- ### thread/start Source: https://learn.chatgpt.com/docs/app-server Starts a fresh thread for a new conversation. ```APIDOC ## thread/start ### Description Starts a fresh thread for a new conversation. Returns the thread details including ID and session ID. ### Parameters - **model** (string) - Required - The model to use (e.g., "gpt-5.4") - **cwd** (string) - Required - Current working directory - **approvalPolicy** (string) - Optional - Approval policy setting - **sandbox** (string) - Optional - Sandbox environment type - **personality** (string) - Optional - Personality setting - **serviceName** (string) - Optional - Integration service name for metrics - **historyMode** (string) - Optional - Experimental: "legacy" or "paginated" - **permissions** (string) - Optional - Beta: Named permission-profile ID - **dynamicTools** (array) - Optional - Experimental: Tools to persist in thread metadata ### Request Example { "method": "thread/start", "id": 10, "params": { "model": "gpt-5.4", "cwd": "/Users/me/project", "approvalPolicy": "never", "sandbox": "workspaceWrite", "personality": "friendly", "serviceName": "my_app_server_client" } } ``` -------------------------------- ### account/login/start (ChatGPT Browser Flow) Source: https://learn.chatgpt.com/docs/app-server Initiates a browser-based login flow for ChatGPT. ```APIDOC ## account/login/start (ChatGPT Browser Flow) ### Description Starts the browser-based login flow, returning an authentication URL for the user to visit. ### Parameters - **type** (string) - Required - Must be "chatgpt". - **useHostedLoginSuccessPage** (boolean) - Optional - Whether to use the hosted success page. - **appBrand** (string) - Optional - The brand identifier, defaults to "codex". ### Request Example { "method": "account/login/start", "id": 3, "params": { "type": "chatgpt", "useHostedLoginSuccessPage": true, "appBrand": "chatgpt" } } ``` -------------------------------- ### GET /healthz Source: https://learn.chatgpt.com/docs/app-server Checks the health status of the server. ```APIDOC ## GET /healthz ### Description Returns 200 OK when the request does not include an Origin header. Requests with an Origin header are rejected with 403 Forbidden. ### Method GET ### Endpoint /healthz ### Response #### Success Response (200) - **Status** (string) - OK #### Error Response (403) - **Status** (string) - Forbidden (returned if Origin header is present) ``` -------------------------------- ### Create a skill directory Source: https://learn.chatgpt.com/docs/build-plugins Initialize the folder structure for a specific skill within a plugin. ```bash mkdir -p my-first-plugin/skills/hello ``` -------------------------------- ### codex plugin add Source: https://learn.chatgpt.com/docs/developer-commands?surface=cli Install a plugin from a configured marketplace. ```APIDOC ## codex plugin add ### Description Install a plugin from a configured marketplace. Use --marketplace or -m when the plugin argument omits @marketplace. ### Parameters - **plugin[@marketplace]** (string) - Required - The plugin identifier, optionally including the marketplace name. - **--marketplace, -m** (string) - Optional - The name of the marketplace. - **--json** (flag) - Optional - Enables automation-friendly output. ``` -------------------------------- ### Coordinate a product launch plan Source: https://learn.chatgpt.com/docs/prompting Use this prompt to generate comprehensive project management documentation based on a product brief. ```text Create a launch plan for the attached product brief. Include the timeline, owners, dependencies, risks, announcement draft, customer FAQ, and a checklist for launch day. Flag any missing decisions before producing the final files. ``` -------------------------------- ### account/login/start Source: https://learn.chatgpt.com/docs/app-server Initiates a login session using externally managed ChatGPT tokens. Requires experimentalApi capability to be enabled. ```APIDOC ## account/login/start ### Description Initiates a login session using externally managed ChatGPT tokens. Clients must set `capabilities.experimentalApi = true` during initialization. ### Request ```json { "method": "account/login/start", "id": 7, "params": { "type": "chatgptAuthTokens", "accessToken": "", "chatgptAccountId": "org-123", "chatgptPlanType": "business" } } ``` ### Response ```json { "id": 7, "result": { "type": "chatgptAuthTokens" } } ``` ``` -------------------------------- ### codex plugin marketplace add Source: https://learn.chatgpt.com/docs/developer-commands?surface=cli Install a plugin marketplace source. ```APIDOC ## codex plugin marketplace add ### Description Install a plugin marketplace from GitHub shorthand, a Git URL, an SSH URL, or a local marketplace root directory. ### Parameters - **source** (string) - Required - The marketplace source location. - **--ref** (string) - Optional - Pin a specific Git ref. - **--sparse** (string) - Optional - Use a sparse checkout for Git-backed repositories (can be repeated). - **--json** (flag) - Optional - Enables automation-friendly output. ``` -------------------------------- ### Start CLI Session Source: https://learn.chatgpt.com/docs/prompting Initialize an interactive Codex session in the terminal. ```bash codex ``` -------------------------------- ### account/login/start Source: https://learn.chatgpt.com/docs/app-server Initiates a login process using various authentication modes. ```APIDOC ## account/login/start ### Description Begin login using one of the supported modes: apiKey, chatgpt, chatgptDeviceCode, or chatgptAuthTokens. ```