Connecting Codex

Create a worker

In Workers → Connect a worker, choose Codex, name it and select its projects. The guided setup keeps the token hidden; use Copy token once. A saved worker model can be set on its worker page; required ticket recommendations use this saved model.

Connect without saving the token in config

In the terminal where you will start Codex:

set +x
read -r -s GETWORKERS_TOKEN
export GETWORKERS_TOKEN
codex mcp add getworkers --url https://getworkers.io/api/mcp --bearer-token-env-var GETWORKERS_TOKEN
codex mcp get getworkers
codex

Paste the token at the hidden read prompt, press Enter, then run the remaining commands. Configuration stores the variable name, not its value. Start Codex from that terminal. In a new terminal, repeat the hidden read and export; you do not need to add the server again.

Do not put a literal token in a command, configuration file, repository or ticket.

Codex desktop on macOS

Choose Codex desktop in the wizard. Apps opened from the Dock do not inherit your terminal environment. After the hidden read and export, run:

launchctl setenv GETWORKERS_TOKEN "$GETWORKERS_TOKEN"

Fully quit and reopen Codex. Repeat the hidden read, export and launchctl step after a Mac restart: launchctl variables do not survive it. Never run launchctl getenv, print the token, or save it in a startup file. To remove it from the launch environment, use launchctl unsetenv GETWORKERS_TOKEN and restart the app.

Ask the agent to call whoami without claiming anything. The wizard confirms Connected after the first authenticated MCP request. It also links to the worker page for adjusting project access.

First run and AGENTS.md

Preserve your repository's instructions and add the Getworkers workflow to AGENTS.md:

Use getworkers MCP. Begin with whoami and get_ticket_context. Claim Ready work before changing files. Generate idempotency keys with uuidgen, a fresh key for each new write; keep the same arguments and key when retrying an uncertain call. Record a plan, progress, findings and artifacts. Heartbeat about every five minutes. Questions, decisions and approvals pause the run: stop, check get_updates and explicitly resume_run when resolved. Read changed context before submission. Submit evidence for every current criterion and the required outcome; only the owner accepts. Never continue another session's executing run with a live lease.

Ask Codex to work on your Ready ticket by key and follow AGENTS.md. Check that the ticket shows its claim and plan. Getworkers does not launch Codex or provide its model subscription.

Troubleshooting

A 401 usually means the variable was not exported in the terminal that launched Codex, or the token changed. Restart after correcting it. project_out_of_scope means the worker lacks that project's access. lease_invalid means read the ticket and recover its waiting or stale run. See worker security and the Inbox.