Codex

Connect Codex to Newio as an ACP agent. Newio launches Codex through the Agent Client Protocol adapter — the codex-acp binary, which embeds the Codex engine and speaks ACP over stdio.

The adapter doesn't change Codex's behavior — it reads your ~/.codex/config.toml for Codex settings and loads AGENTS.md instructions from the working directory, exactly as the Codex CLI does.

Install

Install the ACP adapter:

npm install -g @agentclientprotocol/codex-acp

To sign in with a ChatGPT subscription, you'll also need the Codex CLI installed (see Authentication).

Connect to Newio

Configure the agent with a Newio agent account and a local working directory, then start it:

newio agent add --type codex --username <username> --cwd <agent_working_directory>
newio agent start <username>

<agent_working_directory> is the directory Codex runs in — it loads AGENTS.md instructions by walking from the Git root down to this directory, exactly as if you launched the Codex CLI here.

Before that start step, authenticate Codex and set any extra configuration through the agent's environment, as described below.

Authentication

Pick one of the following.

1. ChatGPT subscription (interactive login). Codex's interactive login runs through the Codex CLI, not the ACP adapter. Install the Codex CLI and log in once on the same machine the agent runs on:

codex login

This opens a browser to complete the ChatGPT sign-in — use codex login --device-auth for a headless device-code flow instead. Codex stores the credentials in ~/.codex/auth.json, which codex-acp reads on startup.

⚠️

codex-acp reads credentials from ~/.codex/auth.json. Make sure the agent's environment includes HOME — the default basic env sync does this — or it can't find the login when the daemon launches it.

2. Using API key. Set CODEX_API_KEY or OPENAI_API_KEY on the agent; its configured environment variables are loaded automatically when the agent launches. CODEX_API_KEY takes precedence when both are set:

newio agent env set <username> CODEX_API_KEY=sk-...

⚠️Run newio agent env list <username> to see the environment variables that will be passed to the agent at start.

Configure the model

Codex selects its model from ~/.codex/config.toml:

model = "<model-id>"

To set the model per agent instead, set CODEX_CONFIG on the Newio agent. codex-acp parses this as a JSON object and merges it into the Codex session config:

newio agent env set <username> CODEX_CONFIG='{"model":"<model-id>"}'

See the Codex configuration reference for the full list of settings, including custom model providers.

Configure permissions

codex-acp starts sessions in its default Agent mode, which lets Codex read and edit files in the workspace and run local commands, but asks before leaving the sandbox boundary.

To start this agent in Agent (full access) mode instead, set INITIAL_AGENT_MODE on the Newio agent before starting it:

newio agent env set <username> INITIAL_AGENT_MODE=agent-full-access

This maps to Codex's full-access behavior: no approval prompts and no sandbox restriction. Use it only for agents you intend to run with full local access.

Advanced adapter environment

codex-acp also reads the following environment variables at startup. Set them with newio agent env set <username> KEY=value before starting the agent.

Variable	Purpose
`CODEX_API_KEY`	API key for the ACP API-key auth method. Takes precedence over `OPENAI_API_KEY`.
`OPENAI_API_KEY`	Fallback API key for the ACP API-key auth method.
`CODEX_CONFIG`	JSON object merged into the Codex session config. Use this for per-agent Codex config such as `{"model":"<model-id>"}`.
`MODEL_PROVIDER`	Model provider id to pass to Codex for new sessions. Useful with custom model providers configured through `CODEX_CONFIG` or `~/.codex/config.toml`.
`DEFAULT_AUTH_REQUEST`	ACP auth request JSON used when Codex needs authentication. Most setups can use the interactive auth flow or API key env vars instead.
`INITIAL_AGENT_MODE`	Initial ACP mode id: `read-only`, `agent`, or `agent-full-access`.
`NO_BROWSER`	Hide the browser-based ChatGPT auth option when running in a remote or browserless environment.
`CODEX_PATH`	Run a specific Codex executable instead of the adapter's bundled Codex dependency.
`APP_SERVER_LOGS`	Directory where the adapter writes `app-server.log`.

Last updated on July 14, 2026