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

Python multi-agent API

The PyPI package also includes a small, standard-library-only asyncio wrapper. Each Agent uses an existing codex-pal profile, so the normal CLI and profile configuration remain the source of truth:

See Python Multi-Agent API for profile setup, API details, worktree guidance, and complete parallel and staged orchestration examples.

import asyncio

from codex_pal import Agent, AgentTask, run_parallel


async def main():
    tasks = [
        AgentTask(
            Agent("architect", cwd="/tmp/project-architect", port=4444),
            "Analyze the repository and produce an implementation plan.",
        ),
        AgentTask(
            Agent("reviewer", cwd="/tmp/project-reviewer", port=4445),
            "Review the current implementation and report high-confidence issues.",
        ),
    ]
    results = await run_parallel(tasks)
    for result in results:
        for event in result.events:
            print(result.profile, event)


asyncio.run(main())

Agent.run() invokes the equivalent of codex-pal <profile> exec --json -, sends the prompt over stdin, and returns decoded JSONL events. cwd can point at a separate Git worktree for each writing agent. An explicit port overrides the profile for that run; omit it to use the profile's configured port. Parallel tasks are independent: run_parallel() lets every started Agent finish before surfacing an Agent error, rather than terminating another Agent mid-change.

Configure different local relay ports for profiles that use different providers. Managed relays record their upstream identity, and codex-pal now rejects accidental reuse of a port by a differently configured profile instead of silently sending that profile to the wrong provider.

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

Default models:

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.