diff --git a/public-docs/codex.md b/public-docs/codex.md
new file mode 100644
index 000000000..2def47a8f
--- /dev/null
+++ b/public-docs/codex.md
@@ -0,0 +1,84 @@
+---
+title: Codex
+description: Run Codex in Paseo using the official Codex CLI and your existing OpenAI account.
+nav: Codex
+order: 24
+category: Providers
+---
+
+# Codex
+
+Paseo runs Codex through the official `codex` CLI and its app-server interface.
+
+## Does Codex cost extra in Paseo?
+
+No. Paseo does not add a charge for Codex. Sign in to the Codex CLI with ChatGPT to use the access included with your ChatGPT plan, or sign in with an API key for usage billed through your OpenAI Platform account.
+
+Your plan's normal Codex limits and OpenAI's standard API pricing still apply.
+
+## Getting started
+
+Install the [Codex CLI](https://learn.chatgpt.com/docs/codex/cli) on the machine running Paseo:
+
+```bash
+npm install -g @openai/codex
+```
+
+Sign in with ChatGPT for subscription access:
+
+```bash
+codex login
+```
+
+Or sign in with an API key for usage billed through your OpenAI Platform account:
+
+```bash
+# macOS or Linux
+printenv OPENAI_API_KEY | codex login --with-api-key
+```
+
+```powershell
+# Windows PowerShell
+$env:OPENAI_API_KEY | codex login --with-api-key
+```
+
+Then confirm the CLI starts:
+
+```bash
+codex
+```
+
+Paseo uses this installation and its existing authentication when you start a Codex agent.
+
+## Codex is missing in Paseo
+
+The ChatGPT desktop app and the Codex CLI are separate installs. Installing the desktop app does not make the `codex` command available to Paseo.
+
+Check whether the CLI is on your `PATH`:
+
+```bash
+# macOS or Linux
+which -a codex
+
+# Windows
+where.exe codex
+```
+
+If the command is not found:
+
+1. Install the [Codex CLI](https://learn.chatgpt.com/docs/codex/cli).
+2. Sign in with ChatGPT or an API key using the commands above. See [Codex authentication](https://learn.chatgpt.com/docs/auth).
+3. Restart Paseo if its daemon was already running when you installed the CLI.
+4. In Paseo, open **Settings → Providers → Codex** and select **Refresh**.
+
+The provider should become available once Paseo can find and start the `codex` command.
+
+## Use Codex in the Paseo terminal
+
+Codex also works inside the Paseo terminal. Open a terminal in your workspace and run `codex` for the standard CLI experience while keeping access to your workspace, git changes, and other Paseo tools.
+
+## See also
+
+- [Supported providers](/docs/supported-providers), for other agents you can run alongside Codex.
+- [Custom providers](/docs/custom-providers), for custom binaries, third-party endpoints, or multiple Codex profiles.
+- [Paseo vs Codex app](/alternatives/codex-app), for a feature comparison.
diff --git a/public-docs/supported-providers.md b/public-docs/supported-providers.md
index ff0bb0b58..22190bb75 100644
--- a/public-docs/supported-providers.md
+++ b/public-docs/supported-providers.md
@@ -15,7 +15,7 @@ For the concept and how Paseo manages providers, see [Providers](/docs/providers
 Work out of the box once the underlying CLI is installed and authenticated.
 
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Anthropic's coding agent with MCP support, streaming, and deep reasoning.
-- [Codex CLI](https://github.com/openai/codex). OpenAI's workspace agent with sandbox controls and optional network access.
+- [Codex](/docs/codex). OpenAI's workspace agent with sandbox controls and optional network access.
 - [OpenCode](https://opencode.ai/). Open-source coding assistant with multi-provider model support.
 - [pi](https://github.com/svkozak/pi-acp). Minimal terminal-based coding agent with multi-provider LLM support.