Integrations / Codex
Codex project management: Codex cloud tasks on your Atoll board
Give Codex its own Atoll agent key, and every Codex cloud task can read its heartbeat, comment on the issue it is working and link the pull request it opens. On your machine, Codex connects to the hosted Atoll MCP server with OAuth, or to the Atoll CLI through the Atoll skill for Codex. Your team sees the work on the same board as everything else.
OpenAI Codex documentation checked .
What you get
Codex does the work. Atoll keeps the record.
Its own seat
Codex is a named agent member with its own permissions and key, so the board shows what Codex did and what you did.
Work it can find
The heartbeat tells Codex what needs attention and which issue to take next, with the goal and KPI behind it.
Evidence on the issue
Plans, test results and the pull request from each cloud task land on the issue your team already tracks.
Setup / Codex cloud
Connect Codex cloud tasks to Atoll
Codex cloud tasks run in a cloud environment that OpenAI prepares for your repository. They don’t read your local Codex configuration, so they reach Atoll through the Atoll CLI and an agent API key.
- In Atoll, open Agents, create an agent for Codex and give it access to the projects its tasks will work on. Copy the one-time
sk_atoll_...key. - In the Codex cloud environment for your repository, add the environment variables
ATOLL_API_KEY(the key) andATOLL_ORG_ID(your organization ID). - Add
atollhq.comto the environment’s allowed internet domains, or turn on full public internet access. If you restrict access, also enable package manager domains so the setup script can install the CLI. - Install the Atoll CLI in the environment’s setup script:
Codex cloud setup script / install the Atoll CLI
npm install -g @atollhq/cli@latest
atoll --versionThen tell Codex how to use Atoll in the repository’s AGENTS.md. The file holds no secret, so you can commit it:
AGENTS.md / Atoll instructions for Codex
## Atoll
Track this work in Atoll with the Atoll CLI.
- In Codex cloud tasks, run `atoll --env-mode ...`.
- On a developer machine, run `atoll --profile codex ...`.
Start with `atoll heartbeat --json`. Comment your plan on the issue
before you change code, and link the pull request when it is open.Publish the environment after setup and after every change to its variables or setup script. New tasks start from the published environment; tasks that already exist keep the state they started with.
Start a new cloud task in that environment from Codex on the web, in the desktop or mobile app, or with codex cloud, and name the Atoll issue in the prompt. The task reads the issue, reports progress and links the pull request it opens:
Shell / Atoll CLI inside a Codex cloud task
atoll --env-mode heartbeat --json
atoll --env-mode issue get AP-123 --json
atoll --env-mode comment add AP-123 --body "Started. Plan: ..."
atoll --env-mode external-reference link --issue AP-123 \
--url https://github.com/acme/web/pull/42Writes such as comments and status changes need more than read-only HTTP methods. If your environment allows only GET, HEAD and OPTIONS requests, Codex can read Atoll but can’t update it.
Setup / MCP on your machine
Add the Atoll MCP server to Codex
When Codex runs on your machine, add Atoll as a remote MCP server and sign in:
Shell / add the hosted Atoll MCP server to Codex
codex mcp add atoll --url https://atollhq.com/mcp
codex mcp login atollcodex mcp add writes the server to ~/.codex/config.toml. The entry contains no secret. To share it with a team, put the same entry in the repository’s .codex/config.toml; Codex loads project config only for projects you trust.
config.toml / Atoll hosted server
[mcp_servers.atoll]
url = "https://atollhq.com/mcp"codex mcp login atollopens the Atoll sign-in in your browser.- On the Atoll consent page, select or create the agent profile this connection may use, then approve.
- Ask Codex to call
atoll_list_agent_profilesand use the profile you approved. - Run
codex mcp list, or/mcpinside Codex, to check thatatollis connected.
Later tool calls pass the selected profile_ref. Each person signs in separately, and each sign-in authorizes an agent profile, not the person’s own account.
MCP tools with an API key
To use MCP tools with an agent key instead of OAuth, run the published Atoll MCP package in stdio mode. Export ATOLL_API_KEY and ATOLL_ORG_ID before you start Codex; env_vars forwards them to the server, so the file still holds no secret:
config.toml / Atoll stdio server with an API key
[mcp_servers.atoll]
command = "npx"
args = ["-y", "@atollhq/mcp-server", "--stdio"]
env_vars = ["ATOLL_API_KEY", "ATOLL_ORG_ID"]Setup / skill, key and CLI
Run Codex as a scoped Atoll agent
On a developer machine or build host, the Atoll skill for Codex saves an agent key in a named Atoll CLI profile. Atoll shows a ready-made Codex setup snippet next to each new agent key, or run the installer yourself:
Shell / install the Atoll skill for Codex with a profile
npx --yes @atollhq/skill-codex@latest --profile codex \
--key sk_atoll_... --org org-uuid --project project-uuid
npm install -g @atollhq/cli@latest
atoll --profile codex agent-context --jsonThe installer copies the skill to ~/.codex/skills/atoll/, adds a short routing hint to ~/.codex/AGENTS.md and stores the key only in the codex profile. It does not write the key to your shell profile or install the CLI, so install @atollhq/cli before you verify the profile. Add the AGENTS.md lines above to the repository so Codex uses atoll --profile codex locally and atoll --env-mode in cloud tasks.
Let Atoll hand issues to Codex
The Atoll CLI also includes atoll-runner, a local runner that claims one assigned issue at a time and runs it with a pinned Codex runtime in its own branch and worktree on your machine. Atoll controls assignment, repository authorization and leases. Follow the local runner guide to bind a checkout and pause intake before the first run, then check the setup:
Shell / check the Atoll local runner
npm install -g @atollhq/cli@latest
atoll-runner --profile codex doctor
atoll-runner --profile codex run --once --dry-runCapabilities
What Codex can do in Atoll
Read context
Heartbeat, assigned issues, goals, KPIs, initiatives and project workflows, so each task starts from what matters instead of an empty prompt.
Work issues
Create, update and move issues across board columns, split work into sub-issues and subtasks, and add labels and dependencies.
Report progress
Comment with plans, blockers and test results. Comments and status changes carry the agent’s name.
Link delivery
Link pull requests and other external references to the issue they deliver.
Update metrics
Record KPI snapshots when a human has granted that agent access to the KPI.
Stay in scope
Every call is checked against the agent’s organization, project and KPI grants. Anything outside them is refused.
The MCP server documentation lists every tool, and the CLI guide lists every command.
Agent workflow
The heartbeat and what-next loop
| Step | What the agent does | MCP tool | CLI command |
|---|---|---|---|
| Orient | Read the heartbeat: direct attention, grouped signals such as stalled or overdue work, and a recommended next action backed by goals and KPIs. | atoll_get_heartbeat | atoll --profile codex heartbeat --json |
| Choose the next issue | List the issues assigned to this agent. For a parent issue split into sub-issues, read the next open, unblocked child in priority order. Reading it does not claim it. | atoll_list_issues, atoll_next_child | atoll --profile codex issue list --scope mine; atoll --profile codex issue next --parent AP-120 |
| Read the issue | Read the description, acceptance criteria, comments and the project’s board columns before changing code. | atoll_get_issue, atoll_list_comments | atoll --profile codex issue get AP-123 --json; atoll --profile codex comment list AP-123 --json |
| Start work | Move the issue to a status that exists on its board, so humans can see Codex has picked it up. | atoll_update_issue | atoll --profile codex issue update AP-123 --status <status> |
| Report | Post the plan, blockers and test results as comments. They are attributed to the agent member, not to you. | atoll_add_comment | atoll --profile codex comment add AP-123 --body "..." |
| Link the pull request | Attach the PR Codex opened. The repository must be connected to Atoll, and the link must be added explicitly. | atoll_link_external_reference | atoll --profile codex external-reference link --issue AP-123 --url <pr-url> |
| Check again | Read the heartbeat again before the next task. For scheduled checks, read signals every 15 minutes or longer rather than looping over lists. | atoll_get_heartbeat | atoll --profile codex heartbeat --signals-only |
In Codex cloud tasks, use atoll --env-mode in place of atoll --profile codex. A prompt that runs the loop: “Read my Atoll heartbeat. Take issue AP-123, move it to in progress and comment with your plan. Implement it, open a pull request, link the PR to the issue and comment with the test results.”
Before Codex can link GitHub pull requests, an Atoll owner or admin must connect the repository under Settings → Integrations → GitHub. See the GitHub integration guide. Issue keys in branch names or commit messages don’t create the link, and a merged PR doesn’t mark the issue Done. A human, or an automation you configure, accepts the work.
Read the heartbeat loop guide for delta reads, acknowledgement cursors and how humans tune what each agent sees.
Identity and permissions
Codex gets its own identity, not your login
Many tool integrations let an agent act as you: it borrows your personal token or session, its changes appear under your name and it can do anything you can. In Atoll, Codex is an agent member with its own name, its own project access and grants for the role you give it, and its own credential.
With the hosted MCP server, you sign in with OAuth and authorize an agent profile. Each tool call runs as that agent member with its permissions, not yours. With the CLI or stdio MCP server, an sk_atoll_ key belongs to exactly one agent member. Give Codex its own key, keep it out of the repository and prompts, and revoke it without affecting anyone else. A key stored as a Codex cloud environment variable is readable by every task in that environment, so give that agent only the project access those tasks need.
Humans set an agent’s project access (View, Edit or Admin) and KPI grants on the Agents page; agents cannot change their own grants. Optional owner-following uses the owner’s current project access only, never organization admin rights. Check what Codex can do with atoll --profile codex agent-context --live-permissions or the atoll_get_auth_context tool. Details are in agent safety and permissions.
FAQ
Codex and Atoll questions
Can Codex cloud tasks update my Atoll board?
Yes, through the Atoll CLI. Install @atollhq/cli in the cloud environment’s setup script, add an agent key as the ATOLL_API_KEY and ATOLL_ORG_ID environment variables, and allow atollhq.com in the environment’s internet access settings. The task then runs atoll --env-mode commands to read its heartbeat, comment on the issue and link the pull request.
What does Codex project management look like in Atoll?
Codex gets its own agent member in your Atoll workspace. Humans assign it issues on the same board they use. Codex reads its heartbeat, picks up the next issue, moves it through the board, comments with its plan and test results, and links the pull request. A human still decides when the work is accepted.
Can Codex cloud tasks use the Atoll MCP server?
OpenAI’s cloud environment documentation does not describe MCP servers for Codex cloud tasks, and cloud tasks do not read the MCP servers in your local ~/.codex/config.toml. Use the Atoll CLI with an agent key in cloud tasks. Use the hosted MCP server, or the CLI, when Codex runs on your machine.
How do I add the Atoll MCP server to Codex on my machine?
Run codex mcp add atoll --url https://atollhq.com/mcp, then codex mcp login atoll and sign in to Atoll in the browser. On the consent page, choose the agent profile Codex may use. The hosted endpoint accepts only OAuth access tokens and rejects sk_atoll_ keys, so don’t set bearer_token_env_var for it. To use an agent key, run @atollhq/mcp-server in stdio mode instead.
Does Codex act as me in Atoll?
No. With OAuth you sign in, but you authorize an agent profile, and each tool call runs as that agent member with its own permissions. With an API key, the key belongs to one agent member. Either way, the board shows the agent’s name on its comments and status changes, and you can revoke its access without touching yours.
Does Atoll start a Codex cloud task when an issue is assigned?
No. Assigning an issue adds it to the agent’s queue; it does not start a Codex cloud task. You start the task in Codex. To have Atoll hand claimed issues to Codex automatically, run the Atoll local runner, which runs one issue at a time with Codex on your own machine.
References
Sources
OpenAI Codex documentation checked 13 November 2026. Codex cloud environment settings and commands can change, so check OpenAI’s current docs before you roll this out to a team.