Skip to content
Back to search

codex-pooler

The full featured self-hosted Codex gateway, for teams, agents and you

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/icoretech/codex-pooler with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/icoretech/codex-pooler'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/icoretech--codex-pooler/badge.svg)](/listings/icoretech--codex-pooler)

HTML

<a href="/listings/icoretech--codex-pooler"><img src="/api/listings/icoretech--codex-pooler/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

This runs the published release image with a local Postgres database. It is the fastest way to try Codex Pooler on a laptop or small server. For normal use, run a versioned, tagged stable release from [GitHub Releases](https://github.com/icoretech/codex-pooler/releases). The `latest` image tag follows the most recently published release, but a version tag keeps the installation reproducible; run from source only in [Local Development](#local-development).

Prerequisites:

- Docker with Compose - Git, if you are cloning the repository - `openssl`

Start Codex Pooler:

git clone https://github.com/icoretech/codex-pooler.git
cd codex-pooler

# Run the latest tagged stable release. Find its version at
# https://github.com/icoretech/codex-pooler/releases, then substitute it here.
export CODEX_POOLER_IMAGE_TAG=<release-tag>

scripts/self-host/generate-env.sh
docker compose pull
docker compose up -d

The first run pulls the app and Postgres images, waits for Postgres health, runs the migration container, then starts the web app.

Open `http://localhost:4000`. On the first visit, create the owner account at `/bootstrap`, then sign in and start with `/admin/pools`.

To verify the first-run redirect before opening a browser:

curl -sS -D - -o /dev/null http://localhost:4000/ | grep -i '^location: /bootstrap'
curl -fsS http://localhost:4000/bootstrap/status

The status endpoint should return `{"status":"ok","bootstrap":"pending"}` on a fresh database.

Useful commands:

docker compose ps
docker compose logs -f app
docker compose down

To upgrade an existing Compose install, set `CODEX_POOLER_IMAGE_TAG` in `.env` to the target tagged stable release, then run:

docker compose pull
docker compose up -d

The Compose stack has a one-shot `migrate` service. It waits for Postgres, runs release migrations, imports the bundled pricing snapshot, and exits before the web app starts. Normal app boot does not migrate the database by itself. If a failed migration needs to be rerun after fixing configuration or database access, run:

docker compose up -d db
docker compose run --rm migrate
docker compose up -d app

Use `http://localhost:4000` for the default Compose stack even if the Phoenix startup banner prints an endpoint URL such as `https://localhost`; the Compose port mapping is the local URL to open. The release image includes the OS timezone database used for operator timezone display.

To remove the local database too:

docker compose down -v

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,594 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <h1 align="center">Codex Pooler</h1>
  2. <p align="center">
  3. <strong>The full featured self-hosted Codex gateway, for teams, agents and you. Works with:</strong><br>
  4. <br>
  5. <a href="#codex-setup" title="Codex CLI and Codex Desktop"><img src=".github/assets/codex-cli-favicon.png" alt="Codex CLI and Codex Desktop" width="24" height="24"></a>
  6. <a href="#opencode-setup" title="OpenCode"><img src=".github/assets/opencode-v2-favicon.png" alt="OpenCode" width="24" height="24"></a>
  7. <a href="#openclaw-setup" title="OpenClaw"><img src=".github/assets/openclaw-favicon.png" alt="OpenClaw" width="24" height="24"></a>
  8. <a href="#hermes-setup" title="Hermes Agent"><img src=".github/assets/hermes-favicon.png" alt="Hermes Agent" width="24" height="24"></a>
  9. <a href="#pi-setup" title="Pi"><img src=".github/assets/pi-favicon.png" alt="Pi" width="24" height="24"></a>
  10. <a href="#omp-setup" title="OMP"><img src=".github/assets/omp-favicon.png" alt="OMP" width="24" height="24"></a>
  11. <a href="#omo-native-setup" title="OMO Native"><img src=".github/assets/omo-favicon.png" alt="OMO Native" width="24" height="24"></a>
  12. <a href="#cursor-setup" title="Cursor"><img src=".github/assets/cursor-favicon.png" alt="Cursor" width="24" height="24"></a>
  13. <a href="#kilo-code-setup" title="Kilo Code"><img src=".github/assets/kilo-favicon.png" alt="Kilo Code" width="24" height="24"></a>
  14. <a href="#trae-setup" title="Trae"><img src=".github/assets/trae-favicon.png" alt="Trae" width="24" height="24"></a>
  15. <a href="#aider-setup" title="Aider"><img src=".github/assets/aider-favicon.png" alt="Aider" width="24" height="24"></a>
  16. <a href="#continue-setup" title="Continue"><img src=".github/assets/continue-favicon.png" alt="Continue" width="24" height="24"></a>
  17. <a href="#cline-setup" title="Cline"><img src=".github/assets/cline-favicon.png" alt="Cline" width="24" height="24"></a>
  18. <a href="#goose-setup" title="Goose"><img src=".github/assets/goose-favicon.png" alt="Goose" width="24" height="24"></a>
  19. <a href="#deepseek-harness-setup" title="DeepSeek Harness"><img src=".github/assets/deepseek-harness-favicon.png" alt="DeepSeek Harness" width="24" height="24"></a>
  20. <a href="#windmill-setup" title="Windmill AI"><img src=".github/assets/windmill-favicon.png" alt="Windmill AI" width="24" height="24"></a>
  21. <a href="#home-assistant-setup" title="Home Assistant"><img src=".github/assets/home-assistant-favicon.png" alt="Home Assistant" width="24" height="24"></a>
  22. <a href="#openhands-setup" title="OpenHands"><img src=".github/assets/openhands-favicon.png" alt="OpenHands" width="24" height="24"></a>
  23. <a href="#openai-python-sdk-setup" title="OpenAI-compatible SDKs"><img src=".github/assets/python-favicon.png" alt="OpenAI-compatible SDKs" width="24" height="24"></a>
  24. <a href="#openai-node-sdk-setup" title="OpenAI-compatible SDKs"><img src=".github/assets/nodejs-favicon.png" alt="OpenAI-compatible SDKs" width="24" height="24"></a>
  25. <a href="#vercel-ai-sdk-setup" title="Vercel AI SDK"><img src=".github/assets/vercel-favicon.png" alt="Vercel AI SDK" width="24" height="24"></a>
  26. </p>
  27. <p align="center">
  28. <strong>English</strong>
  29. ·
  30. <a href="README.zh-CN.md">简体中文</a>
  31. ·
  32. <a href="README.es.md">Español</a>
  33. ·
  34. <a href="README.ja.md">日本語</a>
  35. </p>
  36. <p align="center">
  37. <a href="https://www.codex-pooler.com">Website</a>
  38. ·
  39. <a href="https://www.codex-pooler.com/docs/">Docs</a>
  40. ·
  41. <a href="#quick-start-with-docker-compose">Quick start</a>
  42. ·
  43. <a href="#harness-configuration">Harness</a>
  44. ·
  45. <a href="#configuration">Configuration</a>
  46. ·
  47. <a href="#deployment">Deployment</a>
  48. ·
  49. <a href="https://x.com/icoretech_inc">X</a>
  50. ·
  51. <a href="https://reddit.com/r/CodexPooler">Reddit</a>
  52. </p>
  53. <p align="center">
  54. <a href="https://trendshift.io/repositories/53664?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-53664" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/53664/daily?language=Elixir" alt="icoretech%2Fcodex-pooler | Trendshift" width="250" height="55"/></a>
  55. </p>
  56. <p align="center">
  57. <img src=".github/assets/codex-pooler-readme-banner.png" alt="Codex Pooler gateway overview">
  58. </p>
  59. <table>
  60. <tr>
  61. <td align="center" valign="top" width="33%">
  62. <a href=".github/assets/screen1.png">
  63. <img src=".github/assets/screen1.png" alt="Codex Pooler upstream account readiness" width="100%">
  64. </a><br>
  65. <sub>Upstreams</sub>
  66. </td>
  67. <td align="center" valign="top" width="33%">
  68. <a href=".github/assets/screen2.png">
  69. <img src=".github/assets/screen2.png" alt="Codex Pooler Pool dashboard" width="100%">
  70. </a><br>
  71. <sub>Pools</sub>
  72. </td>
  73. <td align="center" valign="top" width="33%">
  74. <a href=".github/assets/screen3.png">
  75. <img src=".github/assets/screen3.png" alt="Codex Pooler request logs" width="100%">
  76. </a><br>
  77. <sub>Request logs</sub>
  78. </td>
  79. </tr>
  80. </table>
  81. Codex Pooler is a self-hosted gateway for running Codex-compatible agents,
  82. tools, and automation through stable Pool API keys. It works with one upstream
  83. Codex account for credential isolation, client normalization, metadata-only
  84. operations, and saved reset visibility; add more accounts when you want shared
  85. capacity and routing across eligible accounts.
  86. Clients send familiar Codex backend or OpenAI-compatible requests; Codex Pooler
  87. selects an eligible account based on model support, quota evidence, limits,
  88. session continuity, routing policy, and health. The Pool key stays stable while
  89. upstream assignments, lifecycle state, reset policy, and capacity change behind
  90. it.
  91. Operators get one place to manage Pools, accounts, API keys, saved resets,
  92. routing, request accounting, audit logs, and health without storing prompts,
  93. files, audio, images, bearer tokens, or raw Codex secrets. Instance owners keep
  94. the global administration surface, while instance admins work only with their
  95. assigned Pools.
  96. ## Highlights
  97. - 🧩 **Use the tools you already know:** connect Codex, OpenCode and other
  98. supported coding agents, plus apps built with OpenAI-compatible SDKs
  99. - 🔑 **One key for your apps:** connect tools with a Pool API key that stays the
  100. same when you add or replace Codex accounts, without sharing account credentials
  101. - ⚡ **High cache reuse across protocols:** over 95% cached input observed on
  102. HTTP/SSE and WebSockets, backed by cache-aware routing and connection reuse
  103. - 🎯 **Automatic account selection:** send requests to accounts that can serve
  104. the chosen model, with available quota and account health taken into account
  105. - 📏 **Control how much each key can use:** set request limits and daily or
  106. weekly AI usage allowances
  107. - 🚀 **Give agents more room to work:** let them use several tools at once in
  108. Full mode, with Lite compatibility when needed
  109. - 🖼️ **Images and voice, too:** generate and edit images or transcribe audio
  110. through supported apps, using the same Pool API key
  111. - 🛡️ **Keep conversation content private:** track usage and troubleshoot requests
  112. without saving prompts, replies, uploaded files, images or audio
  113. - 🔁 **Keep conversations together:** keep supported sessions linked to the
  114. right account when a client reconnects
  115. - 🔭 **Let users track their own usage:** enable a personal Observatory dashboard
  116. for each key, showing activity, response times and estimated costs
  117. - 🏦 **Put saved resets to use:** see available reset credits and use them to
  118. restore account quota, manually or automatically when enabled
  119. - 🖥️ **Manage everything in one place:** add accounts, manage keys and invites,
  120. check usage and change settings from a browser
  121. - 👥 **Organize teams and projects:** group accounts into Pools with their own
  122. access rules and model choices
  123. - 🤝 **Connect accounts by invitation:** let account owners join a Pool through
  124. a guided browser flow, without sending you credential files
  125. - 🚨 **Know when attention is needed:** receive alerts about low capacity,
  126. account problems and reset events in the dashboard, by email or through webhooks
  127. - 🔎 **Spot model downgrades:** see when the provider
  128. reports a different model from the one sent, or changes the model name during a response
  129. - 🧷 **Fill in missing continuity:** derive stable session identities from cache
  130. keys or conversation IDs when a harness does not send them directly
  131. - 🧱 **Choose who can connect:** optionally allow requests only from approved
  132. networks
  133. - 🐳 **Run it on your own infrastructure:** start with Docker Compose or deploy
  134. on Kubernetes as your needs grow
  135. ## Harness Configuration
  136. Start with a running Codex Pooler instance, a Pool API key, and an installed
  137. client. The examples include `gpt-6-luna`, `gpt-6.1-sol` and `gpt-6-astra`, with
  138. Sol selected by default. Keep the models available to your Pool.
  139. Replace `<pool-api-key>` with your key and run the command for your terminal
  140. before starting the client.
  141. **macOS / Linux / Windows WSL (bash or zsh)**
  142. ```bash
  143. export CODEX_POOLER_API_KEY="<pool-api-key>"
  144. ```
  145. **Windows PowerShell**
  146. ```powershell
  147. $env:CODEX_POOLER_API_KEY = "<pool-api-key>"
  148. ```
  149. These commands set the key for the current terminal. For desktop apps, follow
  150. the linked guide to save the key for the app.
  151. The paths below are defaults. On macOS/Linux, `~` is your home folder.
  152. On Windows, paste paths starting with `%USERPROFILE%`, `%APPDATA%` or
  153. `%LOCALAPPDATA%` into File Explorer's address bar. If you installed a client
  154. inside WSL, use its Linux paths and commands inside WSL. Custom configuration
  155. folders or profiles take precedence over these defaults.
  156. For a local instance:
  157. | Client | Base URL |
  158. | --- | --- |
  159. | Codex CLI / Desktop | `http://localhost:4000/backend-api/codex` |
  160. | Other harnesses and SDKs | `http://localhost:4000/v1` |
  161. For a deployed instance, replace `http://localhost:4000` with your instance's
  162. host, such as `https://codex-pooler.example.com`. Merge snippets into existing
  163. configurations. The examples use the large **828,400-token context** for GPT-6.
  164. Codex CLI and Desktop read the available context size automatically from your Pool.
  165. Each entry covers the basic connection. Its **full setup & extras** link covers
  166. installation, advanced options and troubleshooting. Operator MCP is optional
  167. and uses a separate token; see [Operator MCP Service](#operator-mcp-service).
  168. <a id="codex-setup"></a>
  169. <details>
  170. <summary><img src=".github/assets/codex-cli-favicon.png" alt="Codex logo" width="16" height="16"> Codex CLI and Codex Desktop <code>config.toml</code></summary>
  171. ![Codex Pooler integration for Codex CLI and Codex Desktop](.github/assets/codex-pooler-codex.png)
  172. | System | Configuration file |
  173. | --- | --- |
  174. | macOS / Linux | `~/.codex/config.toml` |
  175. | Windows | `%USERPROFILE%\.codex\config.toml` |
  176. Open `config.toml` at the path for your system and add the following. If you
  177. set `CODEX_HOME`, use the file in that folder instead. Keep `name = "OpenAI"`
  178. to preserve Codex's native features. Catalog discovery is enabled by default;
  179. `model_catalog_url` points it at your Pool.
  180. ```toml
  181. model = "gpt-6.1-sol"
  182. model_provider = "codex-pooler-ws"
  183. [model_providers.codex-pooler-ws]
  184. name = "OpenAI"
  185. base_url = "http://localhost:4000/backend-api/codex"
  186. model_catalog_url = "http://localhost:4000/backend-api/codex/models"
  187. env_key = "CODEX_POOLER_API_KEY"
  188. wire_api = "responses"
  189. supports_websockets = true
  190. requires_openai_auth = true
  191. ```
  192. Restart Codex and choose a model available to your Pool.
  193. If you use Codex Desktop,
  194. follow the full guide to make your API key available to the app.
  195. **[Full setup & extras](https://www.codex-pooler.com/docs/clients/codex-cli-desktop/)** — desktop setup, account settings, existing conversations and the optional custom provider name with its limitations.
  196. </details>
  197. <a id="opencode-setup"></a>
  198. <details>
  199. <summary><img src=".github/assets/opencode-v2-favicon.png" alt="OpenCode logo" width="16" height="16"> OpenCode <code>opencode.jsonc</code></summary>
  200. ![Codex Pooler OpenCode integration](.github/assets/codex-pooler-opencode.png)
  201. | System | Configuration file |
  202. | --- | --- |
  203. | macOS / Linux | `~/.config/opencode/opencode.jsonc` |
  204. | Windows | `%USERPROFILE%\.config\opencode\opencode.jsonc` |
  205. Open `opencode.jsonc` at the path for your system and add the configuration
  206. for your OpenCode version below.
  207. **OpenCode v2**
  208. ```jsonc
  209. {
  210. "$schema": "https://opencode.ai/config.json",
  211. "model": "codex-pooler/gpt-6.1-sol",
  212. "agents": {
  213. "title": {
  214. "model": "codex-pooler/gpt-6-luna"
  215. }
  216. },
  217. "providers": {
  218. "codex-pooler": {
  219. "package": "@opencode/ai/providers/openai/responses",
  220. "settings": {
  221. "baseURL": "http://localhost:4000/v1",
  222. "apiKey": "{env:CODEX_POOLER_API_KEY}",
  223. "transport": "http",
  224. "compaction": {
  225. "type": "summary"
  226. }
  227. },
  228. "models": {
  229. "gpt-6-luna": {
  230. "modelID": "gpt-6-luna",
  231. "capabilities": {
  232. "tools": true,
  233. "input": ["text", "image"],
  234. "output": ["text"]
  235. },
  236. "limit": { "context": 828400, "input": 828400, "output": 32000 },
  237. "settings": {
  238. "reasoningEffort": "high",
  239. "reasoningSummary": "auto"
  240. }
  241. },
  242. "gpt-6.1-sol": {
  243. "modelID": "gpt-6.1-sol",
  244. "capabilities": {
  245. "tools": true,
  246. "input": ["text", "image"],
  247. "output": ["text"]
  248. },
  249. "limit": { "context": 828400, "input": 828400, "output": 32000 },
  250. "settings": {
  251. "reasoningEffort": "high",
  252. "reasoningSummary": "auto"
  253. }
  254. },
  255. "gpt-6-astra": {
  256. "modelID": "gpt-6-astra",
  257. "capabilities": {
  258. "tools": true,
  259. "input": ["text", "image"],
  260. "output": ["text"]
  261. },
  262. "limit": { "context": 828400, "input": 828400, "output": 32000 },
  263. "settings": {
  264. "reasoningEffort": "high",
  265. "reasoningSummary": "auto"
  266. }
  267. }
  268. }
  269. }
  270. }
  271. }
  272. ```
  273. **[OpenCode v2 full setup & extras](https://www.codex-pooler.com/docs/clients/opencode-v2/)** — installation and advanced options.
  274. **OpenCode v1**
  275. ```jsonc
  276. {
  277. "$schema": "https://opencode.ai/config.json",
  278. "model": "openai/gpt-6.1-sol",
  279. "small_model": "openai/gpt-6-luna",
  280. "provider": {
  281. "openai": {
  282. "npm": "@ai-sdk/openai",
  283. "name": "Codex Pooler",
  284. "options": {
  285. "baseURL": "http://localhost:4000/v1",
  286. "apiKey": "{env:CODEX_POOLER_API_KEY}"
  287. },
  288. "models": {
  289. "gpt-6-luna": {
  290. "id": "gpt-6-luna",
  291. "name": "GPT-6 Luna",
  292. "family": "gpt",
  293. "attachment": true,
  294. "reasoning": true,
  295. "tool_call": true,
  296. "temperature": false,
  297. "options": {
  298. "reasoningEffort": "high",
  299. "reasoningSummary": "auto",
  300. "include": ["reasoning.encrypted_content"]
  301. },
  302. "modalities": {
  303. "input": ["text", "image"],
  304. "output": ["text"]
  305. },
  306. "limit": { "context": 828400, "input": 828400, "output": 64000 }
  307. },
  308. "gpt-6.1-sol": {
  309. "id": "gpt-6.1-sol",
  310. "name": "GPT-6.1 Sol",
  311. "family": "gpt",
  312. "attachment": true,
  313. "reasoning": true,
  314. "tool_call": true,
  315. "temperature": false,
  316. "options": {
  317. "reasoningEffort": "high",
  318. "reasoningSummary": "auto",
  319. "include": ["reasoning.encrypted_content"]
  320. },
  321. "modalities": {
  322. "input": ["text", "image"],
  323. "output": ["text"]
  324. },
  325. "limit": { "context": 828400, "input": 828400, "output": 64000 }
  326. },
  327. "gpt-6-astra": {
  328. "id": "gpt-6-astra",
  329. "name": "GPT-6 Astra",
  330. "family": "gpt",
  331. "attachment": true,
  332. "reasoning": true,
  333. "tool_call": true,
  334. "temperature": false,
  335. "options": {
  336. "reasoningEffort": "high",
  337. "reasoningSummary": "auto",
  338. "include": ["reasoning.encrypted_content"]
  339. },
  340. "modalities": {
  341. "input": ["text", "image"],
  342. "output": ["text"]
  343. },
  344. "limit": { "context": 828400, "input": 828400, "output": 64000 }
  345. }
  346. }
  347. }
  348. }
  349. }
  350. ```
  351. **[OpenCode v1 full setup & extras](https://www.codex-pooler.com/docs/clients/opencode/)** — installation and OMO setup.
  352. </details>
  353. <a id="openclaw-setup"></a>
  354. <details>
  355. <summary><img src=".github/assets/openclaw-favicon.png" alt="OpenClaw logo" width="16" height="16"> OpenClaw <code>openclaw.json</code></summary>
  356. ![Codex Pooler OpenClaw integration](.github/assets/codex-pooler-openclaw.png)
  357. | System | Configuration file |
  358. | --- | --- |
  359. | macOS / Linux | `~/.openclaw/openclaw.json` |
  360. | Windows | `%USERPROFILE%\.openclaw\openclaw.json` |
  361. Open `openclaw.json` at the path for your system and add this configuration:
  362. ```json5
  363. {
  364. agents: {
  365. defaults: {
  366. model: {
  367. primary: "openai/gpt-6.1-sol",
  368. list: [{ id: "background", model: "openai/gpt-6-luna" }],
  369. },
  370. compaction: { reserveTokens: 128000 },
  371. },
  372. },
  373. models: {
  374. mode: "merge",
  375. providers: {
  376. openai: {
  377. baseUrl: "http://localhost:4000/v1",
  378. apiKey: "${CODEX_POOLER_API_KEY}",
  379. api: "openai-responses",
  380. agentRuntime: { id: "openclaw" },
  381. timeoutSeconds: 300,
  382. models: [
  383. {
  384. id: "gpt-6-luna",
  385. name: "GPT-6 Luna via Codex Pooler",
  386. reasoning: true,
  387. input: ["text", "image"],
  388. contextWindow: 828400,
  389. contextTokens: 828400,
  390. maxTokens: 128000,
  391. },
  392. {
  393. id: "gpt-6.1-sol",
  394. name: "GPT-6.1 Sol via Codex Pooler",
  395. reasoning: true,
  396. input: ["text", "image"],
  397. contextWindow: 828400,
  398. contextTokens: 828400,
  399. maxTokens: 128000,
  400. },
  401. {
  402. id: "gpt-6-astra",
  403. name: "GPT-6 Astra via Codex Pooler",
  404. reasoning: true,
  405. input: ["text", "image"],
  406. contextWindow: 828400,
  407. contextTokens: 828400,
  408. maxTokens: 128000,
  409. },
  410. ],
  411. },
  412. },
  413. },
  414. }
  415. ```
  416. Restart OpenClaw and start a new conversation.
  417. **[Full setup & extras](https://www.codex-pooler.com/docs/clients/openclaw/)** — background tasks, more models and advanced options.
  418. </details>
  419. <a id="hermes-setup"></a>
  420. <details>
  421. <summary><img src=".github/assets/hermes-favicon.png" alt="Hermes Agent logo" width="16" height="16"> Hermes Agent <code>config.yaml</code></summary>
  422. ![Codex Pooler Hermes Agent integration](.github/assets/codex-pooler-hermes.png)
  423. | System | Folder for `.env` and `config.yaml` |
  424. | --- | --- |
  425. | macOS / Linux | `~/.hermes/` |
  426. | Windows | `%LOCALAPPDATA%\hermes\` |
  427. Open `.env` in the folder for your system and add your Pool API key and
  428. Codex Pooler address. If you set `HERMES_HOME`, use that folder instead:
  429. ```dotenv
  430. OPENAI_API_KEY=<pool-api-key>
  431. OPENAI_BASE_URL=http://localhost:4000/v1
  432. STT_OPENAI_BASE_URL=http://localhost:4000/v1
  433. ```
  434. Add this to `config.yaml` in the same folder, then restart Hermes:
  435. ```yaml
  436. model:
  437. default: gpt-6.1-sol
  438. provider: openai-api
  439. base_url: http://localhost:4000/v1
  440. api_mode: codex_responses
  441. context_length: 828400
  442. supports_vision: true
  443. agent:
  444. image_input_mode: native
  445. api_max_retries: 2
  446. auto_recovery_cycles: 1
  447. image_gen:
  448. provider: openai
  449. openai:
  450. model: gpt-image-2.6-flare
  451. stt:
  452. enabled: true
  453. provider: openai
  454. openai:
  455. model: gpt-4o-transcribe
  456. compression:
  457. threshold: 0.95
  458. auxiliary:
  459. compression:
  460. timeout: 900
  461. ```
  462. This setup includes image generation and voice-to-text. To switch the chat
  463. model, set `model.default` to a model available to your Pool.
  464. Keep all three addresses pointed at your Codex Pooler instance. Your Pool must
  465. also offer the image and transcription models to use those features.
  466. **[Full setup & extras](https://www.codex-pooler.com/docs/clients/hermes/)** — images, speech-to-text, priority processing and troubleshooting.
  467. </details>
  468. <a id="pi-setup"></a>
  469. <details>
  470. <summary><img src=".github/assets/pi-favicon.png" alt="Pi logo" width="16" height="16"> Pi <code>models.json</code></summary>
  471. ![Codex Pooler Pi integration](.github/assets/codex-pooler-pi.png)
  472. | System | Configuration file |
  473. | --- | --- |
  474. | macOS / Linux | `~/.pi/agent/models.json` |
  475. | Windows | `%USERPROFILE%\.pi\agent\models.json` |
  476. Open `models.json` at the path for your system and add this configuration:
  477. ```json
  478. {
  479. "providers": {
  480. "codex-pooler": {
  481. "name": "Codex Pooler",
  482. "baseUrl": "http://localhost:4000/v1",
  483. "api": "openai-responses",
  484. "apiKey": "$CODEX_POOLER_API_KEY",
  485. "authHeader": true,
  486. "models": [
  487. {
  488. "id": "gpt-6-luna",
  489. "name": "GPT-6 Luna via Codex Pooler",
  490. "reasoning": true,
  491. "input": ["text", "image"],
  492. "contextWindow": 828400,
  493. "maxTokens": 128000,
  494. "thinkingLevelMap": { "xhigh": "xhigh" }
  495. },
  496. {
  497. "id": "gpt-6.1-sol",
  498. "name": "GPT-6.1 Sol via Codex Pooler",
  499. "reasoning": true,
  500. "input": ["text", "image"],
  501. "contextWindow": 828400,
  502. "maxTokens": 128000,
  503. "thinkingLevelMap": { "xhigh": "xhigh" }
  504. },
  505. {
  506. "id": "gpt-6-astra",
  507. "name": "GPT-6 Astra via Codex Pooler",
  508. "reasoning": true,
  509. "input": ["text", "image"],
  510. "contextWindow": 828400,
  511. "maxTokens": 128000,
  512. "thinkingLevelMap": { "xhigh": "xhigh" }
  513. }
  514. ]
  515. }
  516. }
  517. }
  518. ```
  519. Add these defaults to `settings.json` in the same folder:
  520. ```json
  521. {
  522. "defaultProvider": "codex-pooler",
  523. "defaultModel": "gpt-6.1-sol",
  524. "enabledModels": [
  525. "codex-pooler/gpt-6-luna",
  526. "codex-pooler/gpt-6.1-sol",
  527. "codex-pooler/gpt-6-astra"
  528. ],
  529. "compaction": { "reserveTokens": 128000 }
  530. }
  531. ```
  532. Then start Pi:
  533. ```bash
  534. pi
  535. ```
  536. **[Full setup & extras](https://www.codex-pooler.com/docs/clients/pi/)** — installation, default models and extra options.
  537. </details>
  538. <a id="omp-setup"></a>
  539. <details>
  540. <summary><img src=".github/assets/omp-favicon.png" alt="OMP logo" width="16" height="16"> OMP <code>models.yml</code></summary>
  541. ![Codex Pooler OMP integration](.github/assets/codex-pooler-omp.png)
  542. | System | Configuration file |
  543. | --- | --- |
  544. | macOS / Linux | `~/.omp/agent/models.yml` |
  545. | Windows | `%USERPROFILE%\.omp\agent\models.yml` |
  546. Open `models.yml` at the path for your system and add this configuration:
  547. ```yaml
  548. providers:
  549. codex-pooler:
  550. baseUrl: http://localhost:4000/v1
  551. api: openai-responses
  552. apiKey: CODEX_POOLER_API_KEY
  553. authHeader: true
  554. remoteCompaction:
  555. enabled: true
  556. api: openai-codex-responses
  557. endpoint: http://localhost:4000/backend-api/codex/responses/compact
  558. v2StreamingEnabled: true
  559. v2Endpoint: http://localhost:4000/backend-api/codex/responses
  560. models:
  561. - id: gpt-6-luna
  562. name: GPT-6 Luna via Codex Pooler
  563. reasoning: true
  564. input: [text, image]
  565. compat:
  566. streamIdleTimeoutMs: 300000
  567. contextWindow: 828400
  568. maxTokens: 128000
  569. - id: gpt-6.1-sol
  570. name: GPT-6.1 Sol via Codex Pooler
  571. reasoning: true
  572. input: [text, image]
  573. compat:
  574. streamIdleTimeoutMs: 300000
  575. contextWindow: 828400
  576. maxTokens: 128000
  577. - id: gpt-6-astra
  578. name: GPT-6 Astra via Codex Pooler
  579. reasoning: true
  580. input: [text, image]
  581. compat:
  582. streamIdleTimeoutMs: 300000
  583. contextWindow: 828400
  584. maxTokens: 128000
  585. ```
  586. Add these defaults to `config.yml` in the same folder:
  587. ```yaml
  588. startup:
  589. setupWizard: false
  590. enabledModels:
  591. - codex-pooler/gpt-6-luna
  592. - codex-pooler/gpt-6.1-sol
  593. - codex-pooler/gpt-6-astra
  594. modelProviderOrder:
  595. - codex-pooler
  596. modelRoles:
  597. default: codex-pooler/gpt-6.1-sol:high
  598. smol: codex-pooler/gpt-6-luna:low
  599. tiny: codex-pooler/gpt-6-luna:minimal
  600. slow: codex-pooler/gpt-6-astra:xhigh
  601. plan: codex-pooler/gpt-6-astra:xhigh
  602. task: codex-pooler/gpt-6.1-sol:high
  603. vision: codex-pooler/gpt-6.1-sol:high
  604. advisor: codex-pooler/gpt-6.1-sol:medium
  605. commit: codex-pooler/gpt-6-luna:minimal
  606. designer: codex-pooler/gpt-6-astra:high
  607. compaction:
  608. enabled: true
  609. thresholdPercent: 80
  610. reserveTokens: 128000
  611. remoteStreamingV2Enabled: true
  612. midTurnEnabled: true
  613. handoffSaveToDisk: true
  614. methodOrder: [remote, soft]
  615. ```
  616. The 80% trigger leaves room for compaction instructions and recent tool results. Keep `reserveTokens` aligned with the output budget. For an existing session already near its limit, see the [compaction recovery notes](https://www.codex-pooler.com/docs/clients/omp/#troubleshooting).
  617. Then start OMP:
  618. ```bash
  619. omp
  620. ```
  621. **[Full setup & extras](https://www.codex-pooler.com/docs/clients/omp/)** — installation, model choices and long conversations.
  622. </details>
  623. <a id="omo-native-setup"></a>
  624. <details>
  625. <summary><img src=".github/assets/omo-favicon.png" alt="OMO logo" width="16" height="16"> OMO Native <code>models.json</code></summary>
  626. Connect the standalone `omo` client and its bundled Senpi engine to your Pool.
  627. For OMO inside OpenCode, use the [OpenCode setup](#opencode-setup).
  628. | System | Configuration file |
  629. | --- | --- |
  630. | macOS / Linux | `~/.omo/agent/models.json` |
  631. | Windows | `%USERPROFILE%\.omo\agent\models.json` |
  632. Merge this provider into `models.json`, keeping any existing providers:
  633. ```json
  634. {
  635. "providers": {
  636. "codex-pooler": {
  637. "baseUrl": "https://codex-pooler.example.com/v1",
  638. "api": "openai-responses",
  639. "apiKey": "$CODEX_POOLER_API_KEY",
  640. "authHeader": true,
  641. "models": [
  642. { "id": "gpt-6.1-sol", "reasoning": true, "defaultThinkingLevel": "medium", "input": ["text"] },
  643. { "id": "gpt-6-luna", "reasoning": true, "defaultThinkingLevel": "low", "input": ["text"] },
  644. { "id": "gpt-6-astra", "reasoning": true, "defaultThinkingLevel": "high", "input": ["text"] }
  645. ]
  646. }
  647. }
  648. }
  649. ```
  650. Keep the `$` in the API-key reference and replace the example URL with your
  651. Pooler's `/v1` URL. Keep only models available to your Pool. Start with Sol:
  652. ```bash
  653. omo --provider codex-pooler --model gpt-6.1-sol --thinking medium
  654. ```
  655. This setup covers text requests. The guide includes saved defaults and a
  656. no-tool connection check.
  657. **[Full setup & extras](https://www.codex-pooler.com/docs/clients/omo-native-senpi/)** — installation, model defaults and connection checks.
  658. </details>
  659. <a id="cursor-setup"></a>
  660. <details>
  661. <summary><img src=".github/assets/cursor-favicon.png" alt="Cursor logo" width="16" height="16"> Cursor <code>Settings → Models → API Keys</code></summary>
  662. ![Codex Pooler Cursor integration](.github/assets/codex-pooler-cursor.png)
  663. In **Settings → Models → API Keys**, enable **OpenAI API Key** and
  664. **Override OpenAI Base URL**. Enter your Pool API key and a public HTTPS URL
  665. such as `https://codex-pooler.example.com/v1`, then select a model available
  666. to your Pool.
  667. Cursor BYOK requires **Pro or higher**. Requests pass through Cursor's
  668. servers, so localhost and private LAN URLs do not work. Use an explicit model
  669. instead of Auto mode.
  670. **[Full setup & extras](https://www.codex-pooler.com/docs/clients/cursor/)** — prerequisites, model selection and connection checks.
  671. </details>
  672. <a id="kilo-code-setup"></a>
  673. <details>
  674. <summary><img src=".github/assets/kilo-favicon.png" alt="Kilo Code logo" width="16" height="16"> Kilo Code <code>kilo.jsonc</code></summary>
  675. ![Codex Pooler Kilo Code integration](.github/assets/codex-pooler-kilo.png)
  676. | System | Configuration file |
  677. | --- | --- |
  678. | macOS / Linux | `~/.config/kilo/kilo.jsonc` |
  679. | Windows | `%USERPROFILE%\.config\kilo\kilo.jsonc` |
  680. Open `kilo.jsonc` at the path for your system and add this configuration:
  681. ```jsonc
  682. {
  683. "$schema": "https://app.kilo.ai/config.json",
  684. "model": "codex-pooler/gpt-6.1-sol",
  685. "enabled_providers": ["codex-pooler"],
  686. "provider": {
  687. "codex-pooler": {
  688. "options": {
  689. "apiKey": "{env:CODEX_POOLER_API_KEY}",
  690. "baseURL": "http://localhost:4000/v1"
  691. },
  692. "models": {
  693. "gpt-6-luna": {
  694. "name": "GPT-6 Luna via Codex Pooler",
  695. "tool_call": true,
  696. "reasoning": true,
  697. "temperature": false,
  698. "attachment": true,
  699. "modalities": {
  700. "input": ["text", "image"],
  701. "output": ["text"]
  702. },
  703. "limit": { "context": 828400, "input": 828400, "output": 64000 }
  704. },
  705. "gpt-6.1-sol": {
  706. "name": "GPT-6.1 Sol via Codex Pooler",
  707. "tool_call": true,
  708. "reasoning": true,
  709. "temperature": false,
  710. "attachment": true,
  711. "modalities": {
  712. "input": ["text", "image"],
  713. "output": ["text"]
  714. },
  715. "limit": { "context": 828400, "input": 828400, "output": 64000 }
  716. },
  717. "gpt-6-astra": {
  718. "name": "GPT-6 Astra via Codex Pooler",
  719. "tool_call": true,
  720. "reasoning": true,
  721. "temperature": false,
  722. "attachment": true,
  723. "modalities": {
  724. "input": ["text", "image"],
  725. "output": ["text"]
  726. },
  727. "limit": { "context": 828400, "input": 828400, "output": 64000 }
  728. }
  729. }
  730. }
  731. }
  732. }
  733. ```
  734. Restart Kilo and select the Codex Pooler model.
  735. **[Full setup & extras](https://www.codex-pooler.com/docs/clients/kilo-code/)** — installation, model choices and extra options.
  736. </details>
  737. <a id="trae-setup"></a>
  738. <details>
  739. <summary><img src=".github/assets/trae-favicon.png" alt="Trae logo" width="16" height="16"> Trae <code>Settings -> Models</code></summary>
  740. Sign in to Trae, open **Settings → Models**, and add a custom model:
  741. | Field | Value |
  742. | --- | --- |
  743. | API format | OpenAI Chat Completions |
  744. | Custom Request URL | `http://localhost:4000/v1` |
  745. | Full URL | Off |
  746. | Model ID | `gpt-6.1-sol` |
  747. | API key | Your Pool API key |
  748. | Model Series | Default |
  749. Repeat this setup with another Model ID to add more models available to your Pool.
  750. Do not add a trailing slash to the URL. Save the model, turn **Auto Mode**
  751. off in the agent model picker, and select it under **Custom Models**.
  752. **[Full setup & extras](https://www.codex-pooler.com/docs/clients/trae/)** — Trae CN, extra settings and connection checks.
  753. </details>
  754. <a id="aider-setup"></a>
  755. <details>
  756. <summary><img src=".github/assets/aider-favicon.png" alt="Aider logo" width="16" height="16"> Aider <code>.aider.conf.yml</code></summary>
  757. ![Codex Pooler Aider integration](.github/assets/codex-pooler-aider.png)
  758. | System | Configuration file |
  759. | --- | --- |
  760. | macOS / Linux | `~/.aider.conf.yml` |
  761. | Windows | `%USERPROFILE%\.aider.conf.yml` |
  762. Open `.aider.conf.yml` at the path for your system and add these settings:
  763. ```yaml
  764. model: openai/gpt-6.1-sol
  765. openai-api-base: http://localhost:4000/v1
  766. ```
  767. Keep the Pool API key in the environment, then start Aider from your repository:
  768. **macOS / Linux / WSL**
  769. ```bash
  770. export OPENAI_API_KEY="$CODEX_POOLER_API_KEY"
  771. aider
  772. ```
  773. **Windows PowerShell**
  774. ```powershell
  775. $env:OPENAI_API_KEY = $env:CODEX_POOLER_API_KEY
  776. aider
  777. ```
  778. If Aider does not recognize the model, follow the additional setup in the
  779. full guide.
  780. To switch models, set `model` to a model available to your Pool, keeping the
  781. `openai/` prefix.
  782. **[Full setup & extras](https://www.codex-pooler.com/docs/clients/aider/)** — additional model setup and editing files.
  783. </details>
  784. <a id="continue-setup"></a>
  785. <details>
  786. <summary><img src=".github/assets/continue-favicon.png" alt="Continue logo" width="16" height="16"> Continue <code>config.yaml</code></summary>
  787. ![Codex Pooler Continue integration](.github/assets/codex-pooler-continue.png)
  788. | System | Configuration file |
  789. | --- | --- |
  790. | macOS / Linux | `~/.continue/config.yaml` |
  791. | Windows | `%USERPROFILE%\.continue\config.yaml` |
  792. Save your Pool API key in Continue as `CODEX_POOLER_API_KEY` using the
  793. [secret setup instructions](https://www.codex-pooler.com/docs/clients/continue/).
  794. Then open `config.yaml` at the path for your system and add this configuration:
  795. ```yaml
  796. name: Codex Pooler
  797. version: 1.0.0
  798. schema: v1
  799. models:
  800. - name: GPT-6 Luna via Codex Pooler
  801. provider: openai
  802. model: gpt-6-luna
  803. apiBase: http://localhost:4000/v1
  804. apiKey: "${{ secrets.CODEX_POOLER_API_KEY }}"
  805. contextLength: 828400
  806. defaultCompletionOptions:
  807. maxTokens: 128000
  808. roles: [chat, edit, apply, summarize]
  809. capabilities: [tool_use, image_input]
  810. - name: GPT-6.1 Sol via Codex Pooler
  811. provider: openai
  812. model: gpt-6.1-sol
  813. apiBase: http://localhost:4000/v1
  814. apiKey: "${{ secrets.CODEX_POOLER_API_KEY }}"
  815. contextLength: 828400
  816. defaultCompletionOptions:
  817. maxTokens: 128000
  818. roles: [chat, edit, apply, summarize]
  819. capabilities: [tool_use, image_input]
  820. - name: GPT-6 Astra via Codex Pooler
  821. provider: openai
  822. model: gpt-6-astra
  823. apiBase: http://localhost:4000/v1
  824. apiKey: "${{ secrets.CODEX_POOLER_API_KEY }}"
  825. contextLength: 828400
  826. defaultCompletionOptions:
  827. maxTokens: 128000
  828. roles: [chat, edit, apply, summarize]
  829. capabilities: [tool_use, image_input]
  830. ```
  831. Select this configuration and the Codex Pooler model in Continue.
  832. **[Full setup & extras](https://www.codex-pooler.com/docs/clients/continue/)** — saving your API key, extra settings and CLI usage.
  833. </details>
  834. <a id="cline-setup"></a>
  835. <details>
  836. <summary><img src=".github/assets/cline-favicon.png" alt="Cline logo" width="16" height="16"> Cline</summary>
  837. ![Codex Pooler Cline integration](.github/assets/codex-pooler-cline.png)
  838. For Cline CLI, save the connection settings with:
  839. **macOS / Linux / WSL**
  840. ```bash
  841. cline auth \
  842. --provider openai \
  843. --apikey "$CODEX_POOLER_API_KEY" \
  844. --baseurl http://localhost:4000/v1 \
  845. --modelid gpt-6.1-sol
  846. ```
  847. **Windows PowerShell**
  848. ```powershell
  849. cline auth --provider openai --apikey "$env:CODEX_POOLER_API_KEY" --baseurl http://localhost:4000/v1 --modelid gpt-6.1-sol
  850. ```
  851. Start Cline and use the saved model. In the IDE extension, choose
  852. **OpenAI Compatible** and enter the same address, API key and model.
  853. Set `--modelid` to a model available to your Pool.
  854. **[Full setup & extras](https://www.codex-pooler.com/docs/clients/cline/)** — IDE setup, extra settings and connection checks.
  855. </details>
  856. <a id="goose-setup"></a>
  857. <details>
  858. <summary><img src=".github/assets/goose-favicon.png" alt="Goose logo" width="16" height="16"> Goose <code>config.yaml</code></summary>
  859. ![Codex Pooler Goose integration](.github/assets/codex-pooler-goose.png)
  860. | System | Configuration file |
  861. | --- | --- |
  862. | macOS / Linux | `~/.config/goose/config.yaml` |
  863. | Windows | `%APPDATA%\Block\goose\config\config.yaml` |
  864. Open `config.yaml` at the path for your system and add this configuration:
  865. ```yaml
  866. GOOSE_PROVIDER: openai
  867. GOOSE_MODEL: gpt-6.1-sol
  868. OPENAI_HOST: http://localhost:4000
  869. OPENAI_BASE_PATH: v1/chat/completions
  870. GOOSE_CONTEXT_LIMIT: 828400
  871. GOOSE_MAX_TOKENS: 128000
  872. ```
  873. Run this in your terminal before starting Goose:
  874. **macOS / Linux / WSL**
  875. ```bash
  876. export OPENAI_API_KEY="$CODEX_POOLER_API_KEY"
  877. ```
  878. **Windows PowerShell**
  879. ```powershell
  880. $env:OPENAI_API_KEY = $env:CODEX_POOLER_API_KEY
  881. ```
  882. To switch models, set `GOOSE_MODEL` to a model available to your Pool.
  883. **[Full setup & extras](https://www.codex-pooler.com/docs/clients/goose/)** — tools, extra settings and Windows setup.
  884. </details>
  885. <a id="deepseek-harness-setup"></a>
  886. <details>
  887. <summary><img src=".github/assets/deepseek-harness-favicon.png" alt="DeepSeek Harness logo" width="16" height="16"> DeepSeek Harness (<code>dsh</code>) <code>cordis.patch.yml</code></summary>
  888. ![Codex Pooler DeepSeek Harness integration](.github/assets/codex-pooler-deepseek.png)
  889. | System | Configuration file |
  890. | --- | --- |
  891. | macOS / Linux | `~/.dsh/profiles/headless/cordis.patch.yml` |
  892. | Windows | `%USERPROFILE%\.dsh\profiles\headless\cordis.patch.yml` |
  893. Run `dsh --profile headless --dump-default-config` once to create the
  894. configuration, then open `cordis.patch.yml` at the path for your system and
  895. add the following. If you set `DSH_HOME`, use its `profiles/headless` folder:
  896. ```yaml
  897. - id: llm-pi-ai
  898. config:
  899. providers:
  900. codex-pooler:
  901. apiKeyEnv: CODEX_POOLER_API_KEY
  902. api: openai-responses
  903. compat:
  904. supportsStrictMode: true
  905. baseURL: http://localhost:4000/v1
  906. models:
  907. - id: gpt-6-luna
  908. contextWindow: 828400
  909. - id: gpt-6.1-sol
  910. contextWindow: 828400
  911. - id: gpt-6-astra
  912. contextWindow: 828400
  913. - id: agent-default-model
  914. config:
  915. provider: codex-pooler
  916. model: gpt-6.1-sol
  917. ```
  918. Keep any existing settings in these entries when adding the configuration.
  919. Start DeepSeek Harness with `dsh --profile headless`.
  920. **[Full setup & extras](https://www.codex-pooler.com/docs/clients/deepseek-harness/)** — installation, tools and extra settings.
  921. </details>
  922. <a id="windmill-setup"></a>
  923. <details>
  924. <summary><img src=".github/assets/windmill-favicon.png" alt="Windmill logo" width="16" height="16"> Windmill AI <code>customai</code> workspace provider</summary>
  925. ![Codex Pooler Windmill AI integration](.github/assets/codex-pooler-windmill.png)
  926. Store a dedicated Pool API key as a Windmill secret variable, then create a
  927. `customai` resource that references it:
  928. ```yaml
  929. description: Codex Pooler API credentials for Windmill AI
  930. value:
  931. api_key: '$var:u/<owner>/codex_pooler'
  932. base_url: http://localhost:4000/v1
  933. headers: {}
  934. resource_type: customai
  935. ```
  936. In workspace AI settings, use the resource you just created and add all three
  937. models. The matching configuration is:
  938. ```yaml
  939. providers:
  940. customai:
  941. resource_path: u/<owner>/codex_pooler
  942. models:
  943. - gpt-6-luna
  944. - gpt-6.1-sol
  945. - gpt-6-astra
  946. default_model:
  947. provider: customai
  948. model: gpt-6.1-sol
  949. metadata_model:
  950. provider: customai
  951. model: gpt-6-luna
  952. ```
  953. Use a URL reachable from the Windmill server; private addresses require
  954. `ALLOW_PRIVATE_AI_BASE_URLS=true` on that server.
  955. **[Full setup & extras](https://www.codex-pooler.com/docs/clients/windmill/)** — resource creation, workspace configuration and supported features.
  956. </details>
  957. <a id="home-assistant-setup"></a>
  958. <details>
  959. <summary><img src=".github/assets/home-assistant-favicon.png" alt="Home Assistant logo" width="16" height="16"> Home Assistant Container <code>OPENAI_BASE_URL</code></summary>
  960. Home Assistant's OpenAI Conversation integration can use Codex Pooler's narrow
  961. OpenAI-compatible `/v1` surface from a Home Assistant Container process. Set the
  962. endpoint in the container environment, then add the integration in Home
  963. Assistant and enter a Pool API key:
  964. ```yaml
  965. services:
  966. homeassistant:
  967. environment:
  968. OPENAI_BASE_URL: https://codex-pooler.example.com/v1
  969. ```
  970. Restart Home Assistant before adding the integration. Choose a model returned by
  971. `GET /v1/models`; use Full serving mode when Assist needs tools. The integration
  972. form has no custom endpoint field, and Home Assistant's official docs do not
  973. endorse third-party endpoints. This is the tested Container setup for Codex
  974. Pooler.
  975. To configure reasoning, open **OpenAI → Conversation subentry → Reconfigure conversation agent** and disable **Recommended model settings**. Enter the exact model ID returned by `GET /v1/models` (for example, `gpt-6-luna` if listed), then choose a **Reasoning effort** supported by that model. **Reasoning summary: Off** only hides the summary; **Reasoning effort: None** disables reasoning where the model supports it.
  976. **[Full setup & extras](https://www.codex-pooler.com/docs/clients/home-assistant/)** — container environment, model selection, request verification and compatibility limits.
  977. </details>
  978. <a id="openhands-setup"></a>
  979. <details>
  980. <summary><img src=".github/assets/openhands-favicon.png" alt="OpenHands logo" width="16" height="16"> OpenHands</summary>
  981. ![Codex Pooler OpenHands integration](.github/assets/codex-pooler-openhands.png)
  982. In OpenHands Agent Canvas, select the native **OpenHands** agent. Under **Settings → LLM → Add LLM Profile → Advanced**, set:
  983. - **Custom Model:** `openai/gpt-6-luna` (or another exact model ID served by your Pool)
  984. - **Base URL:** `https://codex-pooler.example.com/v1`, reachable from the Canvas backend
  985. - **API Key:** your Pool API key
  986. Link this LLM profile under **Settings → Agent** and use Full serving mode for the verified tool workflow. For a local Pooler with Canvas on Docker Desktop, use `http://host.docker.internal:4000/v1`.
  987. **[Full setup & extras](https://www.codex-pooler.com/docs/clients/openhands/)** — Docker setup, screenshots and model profiles.
  988. </details>
  989. <a id="openai-python-sdk-setup"></a>
  990. <details>
  991. <summary><img src=".github/assets/python-favicon.png" alt="Python logo" width="16" height="16"> OpenAI Python SDK</summary>
  992. With OpenAI Python SDK installed and `CODEX_POOLER_API_KEY` set, point the
  993. client at Codex Pooler's `/v1` endpoint:
  994. ```python
  995. import os
  996. from openai import OpenAI
  997. client = OpenAI(
  998. api_key=os.environ["CODEX_POOLER_API_KEY"],
  999. base_url="http://localhost:4000/v1",
  1000. )
  1001. response = client.responses.create(
  1002. model="gpt-6.1-sol",
  1003. input="Write a one-sentence status update.",
  1004. )
  1005. print(response.output_text)
  1006. ```
  1007. Use a model available to your Pool.
  1008. **[Full setup & extras](https://www.codex-pooler.com/docs/clients/openai-compatible/)** — streaming, tools, media and API compatibility.
  1009. </details>
  1010. <a id="openai-node-sdk-setup"></a>
  1011. <details>
  1012. <summary><img src=".github/assets/nodejs-favicon.png" alt="Node.js logo" width="16" height="16"> OpenAI Node SDK</summary>
  1013. With OpenAI Node SDK installed and `CODEX_POOLER_API_KEY` set, point the
  1014. client at Codex Pooler's `/v1` endpoint:
  1015. ```js
  1016. import OpenAI from "openai";
  1017. const client = new OpenAI({
  1018. apiKey: process.env.CODEX_POOLER_API_KEY,
  1019. baseURL: "http://localhost:4000/v1",
  1020. });
  1021. const response = await client.responses.create({
  1022. model: "gpt-6.1-sol",
  1023. input: "Write a one-sentence status update.",
  1024. });
  1025. console.log(response.output_text);
  1026. ```
  1027. Use a model available to your Pool.
  1028. **[Full setup & extras](https://www.codex-pooler.com/docs/clients/openai-compatible/)** — streaming, tools, media and API compatibility.
  1029. </details>
  1030. <a id="vercel-ai-sdk-setup"></a>
  1031. <details>
  1032. <summary><img src=".github/assets/vercel-favicon.png" alt="Vercel logo" width="16" height="16"> Vercel AI SDK</summary>
  1033. With Vercel AI SDK installed and `CODEX_POOLER_API_KEY` set, point the
  1034. client at Codex Pooler's `/v1` endpoint:
  1035. ```ts
  1036. import { createOpenAI } from "@ai-sdk/openai";
  1037. import { generateText } from "ai";
  1038. const pooler = createOpenAI({
  1039. apiKey: process.env.CODEX_POOLER_API_KEY,
  1040. baseURL: "http://localhost:4000/v1",
  1041. });
  1042. const { text } = await generateText({
  1043. model: pooler.responses("gpt-6.1-sol"),
  1044. prompt: "Write a one-sentence status update.",
  1045. });
  1046. console.log(text);
  1047. ```
  1048. Use a model available to your Pool.
  1049. **[Full setup & extras](https://www.codex-pooler.com/docs/clients/openai-compatible/)** — streaming, tools, media and API compatibility.
  1050. </details>
  1051. <details>
  1052. <summary><img src=".github/assets/claude-code-favicon.png" alt="Claude Code logo" width="16" height="16"> Claude Code</summary>
  1053. ![Claude Code on Codex Pooler](.github/assets/codex-pooler-claude.png)
  1054. </details>
  1055. ## Quick Start With Docker Compose
  1056. This runs the published release image with a local Postgres database. It is the
  1057. fastest way to try Codex Pooler on a laptop or small server.
  1058. For normal use, run a versioned, tagged stable release from [GitHub Releases](https://github.com/icoretech/codex-pooler/releases). The `latest` image tag follows the most recently published release, but a version tag keeps the installation reproducible; run from source only in [Local Development](#local-development).
  1059. Prerequisites:
  1060. - Docker with Compose
  1061. - Git, if you are cloning the repository
  1062. - `openssl`
  1063. Start Codex Pooler:
  1064. ```bash
  1065. git clone https://github.com/icoretech/codex-pooler.git
  1066. cd codex-pooler
  1067. # Run the latest tagged stable release. Find its version at
  1068. # https://github.com/icoretech/codex-pooler/releases, then substitute it here.
  1069. export CODEX_POOLER_IMAGE_TAG=<release-tag>
  1070. scripts/self-host/generate-env.sh
  1071. docker compose pull
  1072. docker compose up -d
  1073. ```
  1074. The first run pulls the app and Postgres images, waits for Postgres health, runs
  1075. the migration container, then starts the web app.
  1076. Open `http://localhost:4000`. On the first visit, create the owner account at
  1077. `/bootstrap`, then sign in and start with `/admin/pools`.
  1078. To verify the first-run redirect before opening a browser:
  1079. ```bash
  1080. curl -sS -D - -o /dev/null http://localhost:4000/ | grep -i '^location: /bootstrap'
  1081. curl -fsS http://localhost:4000/bootstrap/status
  1082. ```
  1083. The status endpoint should return `{"status":"ok","bootstrap":"pending"}` on a
  1084. fresh database.
  1085. Useful commands:
  1086. ```bash
  1087. docker compose ps
  1088. docker compose logs -f app
  1089. docker compose down
  1090. ```
  1091. To upgrade an existing Compose install, set `CODEX_POOLER_IMAGE_TAG` in `.env`
  1092. to the target tagged stable release, then run:
  1093. ```bash
  1094. docker compose pull
  1095. docker compose up -d
  1096. ```
  1097. The Compose stack has a one-shot `migrate` service. It waits for Postgres, runs
  1098. release migrations, imports the bundled pricing snapshot, and exits before the
  1099. web app starts. Normal app boot does not migrate the database by itself. If a
  1100. failed migration needs to be rerun after fixing configuration or database
  1101. access, run:
  1102. ```bash
  1103. docker compose up -d db
  1104. docker compose run --rm migrate
  1105. docker compose up -d app
  1106. ```
  1107. Use `http://localhost:4000` for the default Compose stack even if the Phoenix
  1108. startup banner prints an endpoint URL such as `https://localhost`; the Compose
  1109. port mapping is the local URL to open. The release image includes the OS
  1110. timezone database used for operator timezone display.
  1111. To remove the local database too:
  1112. ```bash
  1113. docker compose down -v
  1114. ```
  1115. ## First Runtime Setup
  1116. After bootstrap:
  1117. 1. Create a Pool in `/admin/pools`
  1118. 2. Link, import, or invite one or more Codex accounts in `/admin/upstreams`
  1119. 3. Create a Pool API key in `/admin/api-keys`
  1120. 4. Point Codex or SDK clients at one of the runtime base URLs:
  1121. One upstream account is enough for a working setup. Additional upstreams expand
  1122. the same Pool into shared capacity without changing client credentials.
  1123. Prefer `OAuth` in `/admin/upstreams` for new operator-managed upstream
  1124. accounts when browser authorization is practical. The admin dialog links the
  1125. account, stores resulting credential material through encrypted upstream secret
  1126. storage, and stays metadata-only after completion. Use `Import` only when an
  1127. existing Codex `auth.json` is the right source of credentials.
  1128. Treat an imported Codex `auth.json` as owned by Codex Pooler after import. Do
  1129. not keep using the same `auth.json` from another Codex install, machine, or
  1130. automation unless you accept that provider refresh-token rotation can invalidate
  1131. one copy and move the account to `reauth_required`.
  1132. Hosted invite onboarding and the OAuth device-code fallback use OpenAI's Codex
  1133. device-code authorization. This setup is only needed for hosted invites and the
  1134. OAuth device-code fallback; browser OAuth linking does not depend on it. For a
  1135. personal ChatGPT account, open `chatgpt.com`, go to Settings > Security, and enable
  1136. `Enable device code authorization for Codex`. For workspace-managed accounts,
  1137. ask a workspace admin to enable device-code login for Codex in the workspace
  1138. permissions. OpenAI's [Codex authentication docs](https://developers.openai.com/codex/auth)
  1139. describe device-code login. The invite or fallback flow can fail at the OpenAI
  1140. approval step when device-code authorization is off.
  1141. ```text
  1142. Codex backend base URL: http://localhost:4000/backend-api/codex
  1143. OpenAI SDK base URL: http://localhost:4000/v1
  1144. ```
  1145. Use the generated Pool API key as the bearer token. That key represents the
  1146. Pool, not a single Codex account, so Codex Pooler can pick the best eligible
  1147. account for each request. Raw API keys are shown only once when created or
  1148. rotated.
  1149. ## Operator Roles
  1150. The first bootstrap account is an `instance_owner`. Owners have instance-wide
  1151. administration access: they create Pools, assign operators to Pools, manage
  1152. operators, inspect global jobs, and change system settings.
  1153. Additional operators can be owners or `instance_admin`s. Instance admins are
  1154. Pool-scoped: they can work only with active Pools assigned to them and metadata
  1155. derived from those Pools. If no Pools are assigned, the admin UI shows empty
  1156. Pool-scoped states instead of exposing global data. Archiving or deleting a Pool
  1157. removes future instance-admin visibility for that Pool; historical request and
  1158. audit rows for archived or deleted Pools remain owner-only.
  1159. ## Runtime Compatibility
  1160. Use the client guides when wiring a specific tool. At a glance, clients pick one
  1161. of two public shapes:
  1162. - **Codex backend clients** use `/backend-api/codex` for Codex-native behavior
  1163. such as sessions, compacting, files, audio, images, and backend websockets.
  1164. - **OpenAI-compatible clients** use `/v1` for supported SDK-style Responses,
  1165. chat, files, audio, image, and model-list calls.
  1166. Both paths authenticate with Pool API keys and route through the same Pool
  1167. policy, account health, model support, quota evidence, session continuity, and
  1168. metadata-only accounting. Codex Pooler is intentionally not a wildcard OpenAI
  1169. proxy; unsupported API areas fail predictably. For exact route details, use the
  1170. [Runtime Routes](https://www.codex-pooler.com/docs/reference/runtime-routes/)
  1171. reference and the
  1172. [OpenAI-compatible client guide](https://www.codex-pooler.com/docs/clients/openai-compatible/).
  1173. ## Operator MCP Service
  1174. Codex Pooler includes an optional metadata-only MCP endpoint at `/mcp` for
  1175. trusted operators who want an MCP host to inspect Pools, upstream accounts, Pool
  1176. API key metadata, operators, invites, request logs, audit logs, and MCP service
  1177. status. This operator add-on is not required for Codex Pooler runtime clients.
  1178. The service is read-only and has no mutation tools. It uses the same owner vs
  1179. assigned-Pool visibility model as the admin UI, but connected MCP hosts can read
  1180. the metadata visible to that operator, so only connect hosts you trust with that
  1181. view.
  1182. MCP access uses operator-owned bearer MCP tokens, not Pool API keys, browser
  1183. sessions, cookies, query tokens, invite tokens, upstream tokens, or custom
  1184. headers. Operators manage their own MCP account gate and tokens from
  1185. `/admin/settings?tab=account`; the instance-wide service gate is managed from
  1186. `/admin/system`. Both gates must be enabled before a token works. Raw MCP tokens
  1187. are shown only once when created, and per-key usage tracking, counters, last IP,
  1188. and user-agent history are intentionally not stored.
  1189. The `/mcp` route inherits the runtime ingress IP allowlist and trusted-proxy
  1190. settings. If the allowlist is empty, the firewall is off; if it is configured,
  1191. the resolved client IP must match before MCP authentication or tool dispatch.
  1192. ## Configuration
  1193. `scripts/self-host/generate-env.sh` writes a local `.env` with generated
  1194. secrets and local defaults. Keep that file private and don't reuse generated
  1195. values between public installs.
  1196. Environment variables are only for values the release needs before it can read
  1197. the database:
  1198. - `CODEX_POOLER_IMAGE` and `CODEX_POOLER_IMAGE_TAG`, the release image to run
  1199. - `CODEX_POOLER_HTTP_PORT`, the local host port, default `4000`
  1200. - `DATABASE_URL`, the Postgres connection used by the app
  1201. - `SECRET_KEY_BASE`, Phoenix signing and encryption secret
  1202. - `PHX_HOST`, `PORT`, and `PHX_SERVER`, HTTP endpoint boot settings
  1203. - `OBAN_MODE` and `OBAN_JOBS_QUEUE_LIMIT`, release role and queue topology
  1204. - `DNS_CLUSTER_QUERY`, plus release distribution variables when clustering is on
  1205. - `CODEX_POOLER_TOTP_ENCRYPTION_KEY` and `CODEX_POOLER_TOTP_KEY_VERSION`, TOTP
  1206. encryption root and version
  1207. - `CODEX_POOLER_UPSTREAM_SECRET_KEY` and
  1208. `CODEX_POOLER_UPSTREAM_SECRET_KEY_VERSION`, upstream secret encryption root
  1209. and version; the key must be 32 raw bytes or base64-encoded 32 bytes
  1210. Operational controls such as file limits, ingress trust, gateway diagnostics,
  1211. route-class admission, circuit thresholds, metrics auth, operator email, model
  1212. metadata, upstream timeouts, the OpenAI pricing catalog URL, and SMTP delivery
  1213. live in DB-managed Instance Settings under `/admin/system`. Live settings apply
  1214. to new runtime work through the settings cache. Cached settings reload after save
  1215. through PubSub invalidation; existing leases, in-flight requests, and open streams
  1216. keep the values they started with. The exception is an already-open Responses
  1217. websocket: after a locally applied runtime-firewall settings snapshot, it
  1218. re-evaluates the client IP captured during its handshake.
  1219. Secret Instance Settings stay write-only in the UI. The metrics bearer token is
  1220. stored only as a keyed HMAC digest, fingerprint, and key version. The SMTP
  1221. password is stored encrypted with key version metadata and is recovered only for
  1222. mail send or credential-test paths.
  1223. ## Deployment
  1224. Choose the deployment path that matches how you want to operate Codex Pooler:
  1225. | Path | Use it for | Start here |
  1226. | --- | --- | --- |
  1227. | Docker Compose | A quick self-hosted install on a laptop, lab server, or small single node | [Docker Compose deployment guide](https://www.codex-pooler.com/docs/deployment/docker-compose/) |
  1228. | Kubernetes | Production installs, managed ingress, external Postgres, metrics, and separate runtime roles | [Helm deployment guide](https://www.codex-pooler.com/docs/deployment/helm/) |
  1229. The Kubernetes path uses the
  1230. [`icoretech/codex-pooler` chart](https://github.com/icoretech/helm/tree/main/charts/codex-pooler)
  1231. from the iCoreTech Helm repository. The chart runs one release image as separate
  1232. web, worker, scheduler, and migration roles. For a real install, pin the chart
  1233. `--version`; the chart defaults `image.tag` to the matching `appVersion`.
  1234. ## Need more Codex?
  1235. 👉 [codex-action](https://github.com/icoretech/codex-action) runs OpenAI Codex
  1236. CLI non-interactively in GitHub Actions workflows
  1237. 👉 [codex-docker](https://github.com/icoretech/codex-docker) provides a
  1238. multi-arch OpenAI Codex CLI Docker image built from official upstream releases
  1239. ## Local Development
  1240. Local development runs Phoenix on the host and Postgres through the dev compose
  1241. file:
  1242. ```bash
  1243. make dev
  1244. ```
  1245. `make dev` starts Postgres, prepares the database, imports the vendored OpenAI
  1246. pricing feed, and starts the Phoenix server on `http://localhost:4000`. Logs
  1247. are written to the local development server log.
  1248. Development seeds are optional and only run through the explicit seed task. To
  1249. create a compact idempotent operator baseline with one owner plus four example
  1250. operators, run:
  1251. ```bash
  1252. mix dev.seed compact
  1253. ```
  1254. All seeded operators use `dev-password-123`.
  1255. To recreate a fuller fake dataset for exercising admin UI states without real
  1256. accounts or real request data, run:
  1257. ```bash
  1258. mix dev.seed full
  1259. ```
  1260. The full seed is idempotent and replaces only deterministic `dev-*` fake rows
  1261. owned by the development seed namespace. It includes active/disabled pools,
  1262. active/paused/revoked API keys, upstream accounts in active/refresh/reauth/paused
  1263. states, quota windows, request logs, invites, audit events, and job rows.
  1264. Common checks:
  1265. ```bash
  1266. mix precommit
  1267. mix quality
  1268. docker compose -f docker-compose.dev.yml config
  1269. docker build .
  1270. ```
  1271. Helm chart validation lives with the published chart in the iCoreTech Helm
  1272. repository when Kubernetes deployment behavior or values change.
  1273. `mix test` and `mix precommit` serialize database-backed test runs with a
  1274. PostgreSQL advisory lock keyed by the configured test database, so concurrent
  1275. local runs wait instead of deadlocking the shared sandbox database.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.