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`
`z`, `zai`	`https://api.z.ai/api/paas/v4`	`ZAI_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`
`z`, `zai`	`glm-5.2`
`kimi`, `moonshot`	`kimi-k3`
`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:

Create a GitHub environment named release.
Add an environment secret named CARGO_REGISTRY_TOKEN with a crates.io API token.
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.

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.6.tar.gz (45.6 kB view details)

Uploaded Jul 19, 2026 Source

Built Distributions

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

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

codex_pal-0.1.6-py3-none-win_arm64.whl (625.2 kB view details)

Uploaded Jul 19, 2026 Python 3Windows ARM64

codex_pal-0.1.6-py3-none-win_amd64.whl (654.3 kB view details)

Uploaded Jul 19, 2026 Python 3Windows x86-64

codex_pal-0.1.6-py3-none-musllinux_1_2_x86_64.whl (860.3 kB view details)

Uploaded Jul 19, 2026 Python 3musllinux: musl 1.2+ x86-64

codex_pal-0.1.6-py3-none-musllinux_1_2_aarch64.whl (839.3 kB view details)

Uploaded Jul 19, 2026 Python 3musllinux: musl 1.2+ ARM64

codex_pal-0.1.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (796.5 kB view details)

Uploaded Jul 19, 2026 Python 3manylinux: glibc 2.17+ x86-64

codex_pal-0.1.6-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (779.6 kB view details)

Uploaded Jul 19, 2026 Python 3manylinux: glibc 2.17+ ARM64

codex_pal-0.1.6-py3-none-macosx_11_0_arm64.whl (728.4 kB view details)

Uploaded Jul 19, 2026 Python 3macOS 11.0+ ARM64

codex_pal-0.1.6-py3-none-macosx_10_12_x86_64.whl (748.5 kB view details)

Uploaded Jul 19, 2026 Python 3macOS 10.12+ x86-64

File details

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

File metadata

Download URL: codex_pal-0.1.6.tar.gz
Upload date: Jul 19, 2026
Size: 45.6 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.6.tar.gz
Algorithm	Hash digest
SHA256	`3f2edf042e19e78d86d57aea4de8f74215b6e453358da5bfe356d32b9724338a`
MD5	`8ef75b09b34a236f0dc17e8ae40c857f`
BLAKE2b-256	`34e038b3fa47239265a7cc8ee5322c673eba30df230ff1ac96b1a17aa759ebf3`

See more details on using hashes here.

File details

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

File metadata

Download URL: codex_pal-0.1.6-py3-none-win_arm64.whl
Upload date: Jul 19, 2026
Size: 625.2 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.6-py3-none-win_arm64.whl
Algorithm	Hash digest
SHA256	`977daa3fa80dcbb01e92ff0cd49d6af9bbdf7fa7aea305cf65b68da83201ddc5`
MD5	`c2405b6b1562f494bd8ca481b052abbf`
BLAKE2b-256	`e41514c37c261bb51f8ddfd4ae3c691f8bc20760a3f061ae6f91c324fec000a8`

See more details on using hashes here.

File details

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

File metadata

Download URL: codex_pal-0.1.6-py3-none-win_amd64.whl
Upload date: Jul 19, 2026
Size: 654.3 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.6-py3-none-win_amd64.whl
Algorithm	Hash digest
SHA256	`180bd3ddb555624e51be5878e74efc42f0bd2e91da168141282219a312b93594`
MD5	`4158c391b5db41cd264d1c0300ea0d69`
BLAKE2b-256	`7f2b37b10b4a37913e40daad7c9bc82f1db3c9c2ea81e6f63705e8c509eec293`

See more details on using hashes here.

File details

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

File metadata

Download URL: codex_pal-0.1.6-py3-none-musllinux_1_2_x86_64.whl
Upload date: Jul 19, 2026
Size: 860.3 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.6-py3-none-musllinux_1_2_x86_64.whl
Algorithm	Hash digest
SHA256	`d6f683906f35e9f16b136f417a1e3d18df21d8842c059e2c2dd9a40ee9a0e4c2`
MD5	`152ea98d00d4b3ee3621e1544dae3b1c`
BLAKE2b-256	`76ca86be5d681a546de358a283ea0c848f36f15228cf548d90d3d74a996f7b80`

See more details on using hashes here.

File details

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

File metadata

Download URL: codex_pal-0.1.6-py3-none-musllinux_1_2_aarch64.whl
Upload date: Jul 19, 2026
Size: 839.3 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.6-py3-none-musllinux_1_2_aarch64.whl
Algorithm	Hash digest
SHA256	`b3409aa587f86257816b0c0cf2c520c58631d81e079bcc189f8c216d7297cfd5`
MD5	`52ba1cbed86f5a7c6b0e7f04221230fc`
BLAKE2b-256	`82a20d2272de2ae41f7f89a7c1d1c3119fe67aa7b762d137bbd805ab0de7a9f2`

See more details on using hashes here.

File details

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

File metadata

Download URL: codex_pal-0.1.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Jul 19, 2026
Size: 796.5 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.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`8d05858bbef11cb993d66d3e8825efd449ee4c2d8712437b0397464f9efc447c`
MD5	`bc23ab266962e42c2fea44bc2ae3379d`
BLAKE2b-256	`a2c7fa32d5e305af6b2bede76398520fa9810a45d2f174b0ae20f8efacb188ee`

See more details on using hashes here.

File details

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

File metadata

Download URL: codex_pal-0.1.6-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Upload date: Jul 19, 2026
Size: 779.6 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.6-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm	Hash digest
SHA256	`742901b77f1a5c566361fb05eae4fb8553356409e6929c91836471a2651f2ef7`
MD5	`fbd0ffa88ebf4e8eaca7284174c2962c`
BLAKE2b-256	`9ea6447a2fcaf1c0a9184f909ff66c64cba77fe52e0bd04282c7279cfb046f24`

See more details on using hashes here.

File details

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

File metadata

Download URL: codex_pal-0.1.6-py3-none-macosx_11_0_arm64.whl
Upload date: Jul 19, 2026
Size: 728.4 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.6-py3-none-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`09d5b915a39096184fd80b5124017fcb9ec39727b62910bb544e36f56c494ee7`
MD5	`e6ebe463bd0cab83fee17dbe7e8772d1`
BLAKE2b-256	`7c2be0425be5807e6d23f2b943fcf32d2cf43adc275f39413a6a4f3d0bb5fa2d`

See more details on using hashes here.

File details

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

File metadata

Download URL: codex_pal-0.1.6-py3-none-macosx_10_12_x86_64.whl
Upload date: Jul 19, 2026
Size: 748.5 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.6-py3-none-macosx_10_12_x86_64.whl
Algorithm	Hash digest
SHA256	`64d4f21748b466a8c206a906611c743b65ee4f0b3ce42f1358374ca7cd8bafcc`
MD5	`6cca06af67102d31ddcd7bca0656ca3d`
BLAKE2b-256	`6744b1a7acb3dc80623214c20b52127aed4bfa5896371155d25f2b49674a79ff`