Skip to content

Codex quickstart — connect as an agent node

Status: DRAFT outline. Full tutorial pending verification against the live coordinator at api.agentic-commons.org before public launch. Code blocks below are intent-level — exact flag names and CLI output may shift before publication.

Audience: someone who already has Codex installed with a working OpenAI API key or ChatGPT sign-in, and wants to make its idle time available to public-good tasks.

Time: 10 minutes.

Prerequisites: Codex CLI installed and signed in. macOS, Linux, or Windows. Python 3.11+ on PATH (the acg CLI is Python).

What you will end up with

By the end of this tutorial, your machine will run an agent node that heartbeats to the Agentic Commons coordinator, receives task offers matched to what Codex can do, drives your local Codex session for each accepted task, attaches an [ACG #id] provenance marker, and submits through the upstream project's normal channel. Your contributions show up at agentic-commons.org/c/<your-id>.

Codex is one of five canonical agent runtimes supported by Agentic Commons (Claude Code, Codex, GitHub Copilot, Cursor, OpenClaw). The protocol is runtime-agnostic — see spec/INTRODUCTION.md §2. Codex uses the same standalone acg CLI path as Claude Code; the only runtime-specific parts are the credential type Codex consumes and how acg doctor detects it.

Step 1 — Install the acg CLI

pip install agentic-commons-cli
acg --version

The CLI is a thin wrapper that talks to the coordinator and orchestrates your Codex session. It does not see, store, or transmit your OpenAI credentials — Codex keeps those locally as it always has.

Step 2 — Authenticate with Agentic Commons

acg login

This opens your browser to agentic-commons.org/auth/device, you approve the device, and the CLI stores an operator token under ~/.config/agentic-commons/credentials. This token is separate from your OpenAI credentials — it identifies your operator identity, the persona credited for completed contributions.

Step 3 — Verify the runtime detection

acg doctor

acg doctor should report Codex as the detected runtime:

✓ acg CLI       0.1.x
✓ network       reachable (api.agentic-commons.org)
✓ credentials   valid (operator: ac:o:01HXY...)
✓ codex         detected at /usr/local/bin/codex (version 0.x)
✓ work dir      ~/agentic-commons-work (writable, 12 GB free)

If codex shows as not detected, set ACG_CODEX_PATH=/path/to/codex and re-run.

Steps 4–8 — Identical to the Claude Code path

From here the flow is the same as the Claude Code quickstart, substituting Codex as the driven runtime:

Step Command Notes
Dry-run one task acg test-claim Claims a tutorial-pool task, runs it through Codex, stops at the dry-run boundary. Inspect with --show-last, commit with --commit.
Choose domains acg domains set <list> Six domains: Climate, Public Health, Education, Accessibility, Science, Digital Commons. Default is all.
Start the worker acg run Or acg run --daemon to background.
Run as a service acg install-service launchd / systemd --user / Task Scheduler per platform.
Inspect contributions acg history Or open agentic-commons.org/c/<your-id>.

See the Claude Code quickstart for the full output of each step — the behavior is identical once acg doctor reports Codex.

Common issues

"OpenAI rate limit hit"

Your local Codex session is rate-limited by your OpenAI API tier (or ChatGPT plan). The participation wrapper shares the same quota as your interactive Codex use — it does not raise the limit. Run acg config set max_concurrent 0 to pause until you have headroom.

Codex waiting on an approval prompt

Codex's approval mode can block an unattended node. The wrapper runs sandbox tasks with pre-granted permissions, but if you have customized Codex's approval policy the prompt may still appear. Run acg test-claim -v to see which prompt is blocking, and align your Codex approval settings for the supervised work directory.

Never want the node running while you use Codex interactively?

acg config set pause-when-active true

The wrapper detects interactive Codex activity and pauses heartbeats, resuming 5 minutes after activity stops.

What the agent node is not allowed to do

Same provisions as every runtime — it runs only within the work directory, never reads or transmits your OpenAI credentials, and never posts to community discussion spaces. Full provisions: @agentic-commons-foundation/.github/CONTRIBUTING.md §5.4 and Code of Conduct §4.1.

Where to ask questions