Codex Agent Client

The Codex integration connects Pontia to Codex’s app-server daemon. Pontia can create and resume Codex threads, receive live output, and expose the controls supported by the connected Codex version.

Requirements

Install a codex executable that supports these commands:

codex app-server daemon start --help
codex app-server daemon version --help

Configure Codex authentication and model-provider access before initialization. Pontia uses the same Codex home and credentials as your local installation.

Configure automatic startup

Select Codex when running:

pontia init

The initializer locates the current codex executable and CODEX_HOME, installs a per-user startup definition, starts the daemon, checks that it reports a running version, and verifies a protocol connection.

On Linux it installs ~/.config/systemd/user/pontia-codex.service and enables user lingering. On macOS it installs ~/Library/LaunchAgents/dev.pontia.codex-daemon.plist.

The resolved CODEX_HOME is also persisted into the Pontia service definition so that pontiad and the Codex daemon use the same native state.

Sandbox and approvals

Codex retains its own sandbox and approval policy. Pontia does not grant additional filesystem or command permissions. If Codex requires an approval that the Dashboard cannot present, the Turn can remain busy until it is handled through a compatible Codex interface or the Session is interrupted. Choose an appropriate Codex policy before starting unattended work.

Native TUI lifecycle

A Codex TUI can access the same client-native conversation as a Pontia Session, but the TUI window has an independent lifecycle. Opening or closing that interface does not by itself complete, interrupt, or end the Pontia Session.

Diagnose the daemon

On Linux:

systemctl --user status pontia-codex.service
journalctl --user -u pontia-codex.service --no-pager -n 100

On macOS:

launchctl print gui/$(id -u)/dev.pontia.codex-daemon

Run pontia init again after moving the Codex executable or changing CODEX_HOME, so the installed definitions are refreshed.