codex-pal

codex-pal launches Codex CLI through codex-relay so Codex can use OpenAI-compatible providers that do not natively implement the Responses API.

It is intentionally a small launcher:

  • starts or reuses a local codex-relay sidecar;
  • injects per-invocation Codex config with -c, leaving ~/.codex/config.toml untouched;
  • maps common providers to upstream URLs and API-key environment variables;
  • hands the terminal to codex.

Install

From crates.io:

cargo install codex-pal

From PyPI:

pipx install codex-pal

The PyPI package installs codex-relay as a runtime dependency. codex-pal finds that dependency beside its own executable (including in pipx's private environment) before searching PATH. To expose codex-relay as a standalone shell command too, install with pipx install codex-pal --include-deps.

The Cargo package also declares the codex-relay crate dependency, but Cargo does not install dependency binaries onto PATH when installing a binary crate; if you install with Cargo, install both tools:

cargo install codex-pal codex-relay

Usage

codex-pal has two interfaces:

  • a complete, explicit interface for scripts and debugging;
  • a profile interface for humans.

Human-friendly profiles

export DEEPSEEK_API_KEY=...
codex-pal deepseek

export DASHSCOPE_API_KEY=...
codex-pal qwen

export OPENROUTER_API_KEY=...
codex-pal openrouter

The first run creates a profile under ~/.config/codex-pal/config.toml when the profile name matches a built-in provider. Later runs reuse it.

Configure or modify a profile:

codex-pal deepseek config --model deepseek-v4-pro --port 4555
codex-pal deepseek show
codex-pal profiles
codex-pal providers
codex-pal deepseek status
codex-pal deepseek stop
codex-pal deepseek restart

Custom profile:

export EXAMPLE_API_KEY=...
codex-pal work-llm config \
  --provider custom \
  --upstream https://llm.example.com/v1 \
  --api-key-env EXAMPLE_API_KEY \
  --model vendor/model
codex-pal work-llm

Complete explicit interface

Use run when every setting should be supplied by arguments:

codex-pal run \
  --provider deepseek \
  --model deepseek-v4-pro \
  --port 4444 \
  --approval never \
  --sandbox workspace-write

Custom one-shot launch:

codex-pal run \
  --provider custom \
  --upstream https://llm.example.com/v1 \
  --api-key-env EXAMPLE_API_KEY \
  --model vendor/model

Useful flags:

codex-pal relay status --port 4444
codex-pal relay stop --port 4444
codex-pal relay-config --provider openrouter
codex-pal run --provider deepseek --model deepseek-v4-pro --print-codex-command
codex-pal run --provider deepseek --model deepseek-v4-pro --ask
codex-pal run --provider deepseek --model deepseek-v4-pro --no-sandbox

Use an existing remote codex-relay service instead of starting a local sidecar:

codex-pal run \
  --provider deepseek \
  --model deepseek-v4-pro \
  --relay-url https://relay.example.com

codex-pal deepseek --relay-url https://relay.example.com
codex-pal deepseek config --relay-url https://relay.example.com

--relay-url accepts either the relay root URL or its /v1 base URL. When it is set, codex-pal skips local relay process management and points Codex at the remote relay.

Arguments left after codex-pal consumes its profile or launch options are appended to the codex invocation, so Codex subcommands and flags can be used directly:

codex-pal run --provider deepseek --model deepseek-v4-pro exec --skip-git-repo-check "summarize this repo"
codex-pal deepseek exec --skip-git-repo-check "summarize this repo"
codex-pal deepseek --oss

Use -- when you need to force a later argument to be handled by Codex even if it looks like a codex-pal option:

codex-pal deepseek -- --model gpt-5.5

For relay-backed providers, codex-pal also injects a temporary Codex model_catalog_json file so the in-session /model picker lists models for the selected provider instead of only Codex's bundled OpenAI catalog. If Codex's catalog command is unavailable, launch still continues with the chosen -m model and prints a warning.

Provider Profiles

Provider Upstream API key env
deepseek https://api.deepseek.com/v1 DEEPSEEK_API_KEY
kimi, moonshot https://api.moonshot.cn/v1 MOONSHOT_API_KEY
qwen, dashscope https://dashscope.aliyuncs.com/compatible-mode/v1 DASHSCOPE_API_KEY
mistral https://api.mistral.ai/v1 MISTRAL_API_KEY
groq https://api.groq.com/openai/v1 GROQ_API_KEY
xai, grok https://api.x.ai/v1 XAI_API_KEY
openrouter https://openrouter.ai/api/v1 OPENROUTER_API_KEY

Default models:

Provider Default model
openai gpt-5.5
deepseek deepseek-v4-pro
kimi, moonshot kimi-k2.7-code
qwen, dashscope qwen3.7-max
mistral mistral-medium-3-5+2
groq openai/gpt-oss-120b
xai, grok grok-4.3
openrouter openrouter/auto

Development

cargo test
cargo fmt --check
maturin build

Release

Releases are tag-driven from GitHub Actions.

One-time setup:

  1. Create a GitHub environment named release.
  2. Add an environment secret named CARGO_REGISTRY_TOKEN with a crates.io API token.
  3. On PyPI, create a pending Trusted Publisher for:
    • project: codex-pal
    • owner: MetaFARS
    • repository: codex-pal
    • workflow: release.yml
    • environment: release

Publish:

git tag v0.1.1
git push origin v0.1.1

The release workflow builds all wheels and the sdist, publishes to PyPI via Trusted Publishing, publishes the Rust crate to crates.io, and creates a GitHub Release with the built artifacts.

Project links

Data verified by PyPI on Jul 19, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.2.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for mingli.yuan from gravatar.com mingli.yuan

Credits

Author: MetaFARS

GitHub Statistics

Data verified by PyPI on Jul 19, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Tags

codex codex-relay openai-compatible llm cli

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

codex_pal-0.1.5.tar.gz (45.1 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

codex_pal-0.1.5-py3-none-win_arm64.whl (625.4 kB view details)

Uploaded Python 3Windows ARM64

codex_pal-0.1.5-py3-none-win_amd64.whl (653.7 kB view details)

Uploaded Python 3Windows x86-64

codex_pal-0.1.5-py3-none-musllinux_1_2_x86_64.whl (859.2 kB view details)

Uploaded Python 3musllinux: musl 1.2+ x86-64

codex_pal-0.1.5-py3-none-musllinux_1_2_aarch64.whl (839.9 kB view details)

Uploaded Python 3musllinux: musl 1.2+ ARM64

codex_pal-0.1.5-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (796.0 kB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

codex_pal-0.1.5-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (779.7 kB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

codex_pal-0.1.5-py3-none-macosx_11_0_arm64.whl (727.8 kB view details)

Uploaded Python 3macOS 11.0+ ARM64

codex_pal-0.1.5-py3-none-macosx_10_12_x86_64.whl (748.2 kB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

Details for the file codex_pal-0.1.5.tar.gz.

File metadata

  • Download URL: codex_pal-0.1.5.tar.gz
  • Upload date:
  • Size: 45.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for codex_pal-0.1.5.tar.gz
Algorithm Hash digest
SHA256 64067a114fa69637202bd8f4503b5d71e7aee398a31da9132f250d7342a5eabd
MD5 7ba3a301aeb0435787fbcac6dfc8a553
BLAKE2b-256 6df16b92e6e73ef6ca9cbf1c2bac9e82d7c2ae60292a26f3deff6def30b40f1c

See more details on using hashes here.

File details

Details for the file codex_pal-0.1.5-py3-none-win_arm64.whl.

File metadata

  • Download URL: codex_pal-0.1.5-py3-none-win_arm64.whl
  • Upload date:
  • Size: 625.4 kB
  • Tags: Python 3, Windows ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for codex_pal-0.1.5-py3-none-win_arm64.whl
Algorithm Hash digest
SHA256 42053ba3b78d0dac454be448910b18fdc7b26f67333da849819b0f234e9e2435
MD5 be62476f08d492ae60813ac98d8120ad
BLAKE2b-256 b00c92b9cc4cf953e1d85cb7a7fb2e2a9b57aec9c71ac2a7d216260983c62a0c

See more details on using hashes here.

File details

Details for the file codex_pal-0.1.5-py3-none-win_amd64.whl.

File metadata

  • Download URL: codex_pal-0.1.5-py3-none-win_amd64.whl
  • Upload date:
  • Size: 653.7 kB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for codex_pal-0.1.5-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 0fbd6da00336f95aced6ae9efc7adcd2be15989085b22e5241fac104629b000d
MD5 cb671aeea933e2dc0254797c6b51ba2f
BLAKE2b-256 785683dfcf5d76a8dabd8d0f624cfeb6d128bc7cc75104d2d402f1244feee458

See more details on using hashes here.

File details

Details for the file codex_pal-0.1.5-py3-none-musllinux_1_2_x86_64.whl.

File metadata

  • Download URL: codex_pal-0.1.5-py3-none-musllinux_1_2_x86_64.whl
  • Upload date:
  • Size: 859.2 kB
  • Tags: Python 3, musllinux: musl 1.2+ x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for codex_pal-0.1.5-py3-none-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 0102100bc813569babcea6dfb1074285af2640b22925e9b0ab87f868aa0f87ab
MD5 14e9027d05d4dca8fdbbc1448e7ceb96
BLAKE2b-256 bb8d3058740f434df0991604505d40dfef9e4d6c077796b238b92e6bc5d6706b

See more details on using hashes here.

File details

Details for the file codex_pal-0.1.5-py3-none-musllinux_1_2_aarch64.whl.

File metadata

  • Download URL: codex_pal-0.1.5-py3-none-musllinux_1_2_aarch64.whl
  • Upload date:
  • Size: 839.9 kB
  • Tags: Python 3, musllinux: musl 1.2+ ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for codex_pal-0.1.5-py3-none-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 acf445cad87d3b8f065a7eeef9d30f4e4c429262e16deae4ae826c66dda45f11
MD5 2d8f8527f3b1218ee3e8248e6ed313d5
BLAKE2b-256 5d5ca683853c4facfb3003c13b2afd960b86daa33038b6d656c2464adc865c8e

See more details on using hashes here.

File details

Details for the file codex_pal-0.1.5-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

  • Download URL: codex_pal-0.1.5-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
  • Upload date:
  • Size: 796.0 kB
  • Tags: Python 3, manylinux: glibc 2.17+ x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for codex_pal-0.1.5-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 36e698ffd6e98499d5d5ea35a6f1d24072e14949c35c9cdfc7d758aa51c282ef
MD5 99b5d285867667a52102b076e0493f60
BLAKE2b-256 1cbb204decbd64d374726814f7b64466478d0dfb07df8d0268098f6c3eff3405

See more details on using hashes here.

File details

Details for the file codex_pal-0.1.5-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

  • Download URL: codex_pal-0.1.5-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
  • Upload date:
  • Size: 779.7 kB
  • Tags: Python 3, manylinux: glibc 2.17+ ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for codex_pal-0.1.5-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 3eb5d88cc6c2855d8a7b17c15783cb69fb093c617e00fdc8467643a4681f946b
MD5 b5e4459f0030f547e77ec119162a4a49
BLAKE2b-256 6944c6dc100f6b5b91b8ce3d99b60ce10888835d33d854c896dbb2bac951daee

See more details on using hashes here.

File details

Details for the file codex_pal-0.1.5-py3-none-macosx_11_0_arm64.whl.

File metadata

  • Download URL: codex_pal-0.1.5-py3-none-macosx_11_0_arm64.whl
  • Upload date:
  • Size: 727.8 kB
  • Tags: Python 3, macOS 11.0+ ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for codex_pal-0.1.5-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 45ed9a9c448a853d62e28b4e6f1879af6039e08ce0bb0e6c76a5b9f68ece848c
MD5 7dd3aeb383a572b20e826311f3a91e64
BLAKE2b-256 07641c99a48f31c7a645189edc813276d0f3992f392183411f49bbadf835062e

See more details on using hashes here.

File details

Details for the file codex_pal-0.1.5-py3-none-macosx_10_12_x86_64.whl.

File metadata

  • Download URL: codex_pal-0.1.5-py3-none-macosx_10_12_x86_64.whl
  • Upload date:
  • Size: 748.2 kB
  • Tags: Python 3, macOS 10.12+ x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for codex_pal-0.1.5-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 61fee5e350cdebd3889f5cf0315ec7d28a4a2992928da4dbfd8e928e3d757a6f
MD5 41390de116665ccccedaf4d259d4726c
BLAKE2b-256 647258345050b1fd77a7a67750e8d671e08fee9fc592786214c3659e8752d47a

See more details on using hashes here.

Release history Release notifications | RSS feed

0.2.1

9 files

0.2.0

9 files

0.1.6

9 files

This release

0.1.5 This release

9 files

0.1.4

9 files

0.1.3

16 files

0.1.2

16 files

0.1.1

16 files

0.1.0

16 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page