---
slug: "pi-web-providers-codex-cf"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/arpagon/pi-web-providers-codex-cf@main/README.md"
repo: "https://github.com/arpagon/pi-web-providers-codex-cf"
source_file: "README.md"
branch: "main"
---
# pi-web-providers-codex-cf

Minimal Pi web providers extension for Codex authenticated with a ChatGPT subscription and Cloudflare Browser Rendering:

| Pi tool | Provider |
| --- | --- |
| `web_search` | Codex SDK / ChatGPT subscription |
| `web_answer` | Codex SDK / ChatGPT subscription |
| `web_research` | Codex SDK / ChatGPT subscription |
| `web_contents` | Cloudflare Browser Rendering markdown endpoint |

This package is a narrow derivative of `arpagon/pi-web-providers-az-cf`, which itself is a security-oriented vivefork of `mavam/pi-web-providers`. It replaces Azure/OpenAI API-credit usage with the local Codex authentication used by a ChatGPT subscription.

## Why this exists

Reducing software supply-chain and runtime attack surface is a primary goal of this project.

Upstream `mavam/pi-web-providers` supports a broad provider marketplace. That functionality requires many vendor SDKs and can install hundreds of third-party packages transitively. Most of those providers are not used in this environment, so accepting their code, install scripts, vulnerabilities, and maintenance risk would provide no practical benefit.

This extension deliberately keeps only the two required provider families:

- Codex for search, grounded answers, and research.
- Cloudflare Browser Rendering for page extraction.

Codex subscription authentication requires the official `@openai/codex-sdk`, so this variant cannot have an empty runtime dependency tree like `pi-web-providers-az-cf`. The tradeoff is explicit and narrowly bounded: one direct runtime SDK, its official Codex CLI package, and the platform-specific Codex binary. Cloudflare remains a small direct REST implementation instead of pulling the broad generated Cloudflare SDK.

Adding another provider or runtime dependency requires an explicit security and maintenance justification; feature parity with upstream is not a goal.

## Authentication

Authenticate Codex before using the extension:

```sh
codex login
```

The official `@openai/codex-sdk` spawns its bundled Codex CLI and uses the existing Codex login under `~/.codex`. No OpenAI or Azure API key is required for the normal ChatGPT subscription path.

Cloudflare still requires an API token and account ID.

## Runtime dependency policy

The only direct runtime dependency is `@openai/codex-sdk`. It is intentional: ChatGPT subscription authentication and Codex execution are provided by the official SDK and its bundled CLI. Cloudflare continues to use direct `fetch`, avoiding the large Cloudflare SDK surface for one endpoint.

Do not add other providers or SDKs without explicit approval.

## Configuration

The extension reads `~/.pi/agent/web-providers.json`:

```json
{
  "tools": {
    "search": "codex",
    "contents": "cloudflare",
    "answer": "codex",
    "research": "codex"
  },
  "providers": {
    "codex": {
      "options": {
        "networkAccessEnabled": true,
        "webSearchEnabled": true,
        "search": { "webSearchMode": "live" },
        "answer": { "webSearchMode": "live" },
        "research": {
          "webSearchMode": "live",
          "modelReasoningEffort": "high"
        }
      }
    },
    "cloudflare": {
      "credentials": { "api": "CLOUDFLARE_API_TOKEN" },
      "accountId": "CLOUDFLARE_ACCOUNT_ID"
    }
  }
}
```

Codex capability options support:

- `model`
- `modelReasoningEffort`: `minimal`, `low`, `medium`, `high`, or `xhigh`
- `webSearchMode`: `disabled`, `cached`, or `live`
- `instructions`

Optional provider-level Codex fields are compatible with upstream:

- `codexPath`
- `baseUrl`
- `credentials.api` for explicit API-key operation instead of subscription auth
- `env`
- `config`
- `options.additionalDirectories`

Credential and environment-map values can be literal strings, environment variable names, or `!command` references.

## Safety model

Each Codex turn runs with:

- `sandboxMode: "read-only"`
- `approvalPolicy: "never"`
- web search enabled
- network access enabled
- the active Pi project as working directory

The extension asks Codex for structured output and does not grant write access to the project.

## Commands

```text
/web-providers
```

Shows the config path.

```text
/web-providers init
```

Writes a template config to `~/.pi/agent/web-providers.json`.

## Development

```sh
npm install
npm run check
npm test
npm run build
```

Live Pi smoke test:

```sh
npm run e2e:pi
```

Select a tool when needed:

```sh
PI_WEB_PROVIDERS_E2E_TOOL=web_search npm run e2e:pi
```

Live tests consume ChatGPT/Codex usage and Cloudflare quota.

## Publishing

The package is prepared for npm trusted publishing through `.github/workflows/publish.yml`.

Configure npm trusted publishing with:

- repository: `arpagon/pi-web-providers-codex-cf`
- workflow: `publish.yml`
- environment: `npm`

Then publish a version tag:

```sh
npm version patch
git push --follow-tags
```

## Non-goals

No Azure/OpenAI Responses API, Brave, Claude, Gemini, Exa, Firecrawl, Linkup, Ollama, Parallel, Perplexity, Serper, Tavily, Valyu, or general provider marketplace support.