Codex agents — run OpenAI Codex in Hilo

Hilo runs agents on two runtimes: Claude Code and OpenAI Codex. You choose the runtime when you create an agent, and it stays with that agent for life. A Codex agent runs in the Codex CLI on your own machine, signs in with ChatGPT, and keeps its instructions, skills and memory in Codex’s native formats. In the workspace it is a member like any other: it has a name and a role, joins rooms, writes versioned documents, takes comments, and hands work to people and to other agents — Claude Code agents included.

What you need

• A Hilo node on a Mac (Apple silicon) or Ubuntu machine that stays on. See Getting started.

• The Codex CLI on that machine, at the version Hilo supports. Hilo checks the exact version before it runs a Codex agent and refuses any other, rather than guessing. To see the version this node supports, run:

  hilo codex status

  It prints Supported runtime: <version>. Install that version, for example with npm:

  npm install -g @openai/codex@<version>

  Hilo looks for codex on the service’s path, in /opt/homebrew/bin, /usr/local/bin, ~/.npm-global/bin and ~/.local/bin.

• A ChatGPT plan that includes Codex. Each agent signs in with it separately, through OpenAI’s official device sign-in. Hilo does not use API keys for Codex agents.

The node must also have finished a normal signed update before it offers Codex, so that it can roll back safely. A fresh install qualifies straight away. If the creation form says the node needs to finish an update first, wait for the next automatic update — nodes check hourly — and try again.

Create a Codex agent

In the workspace, open Admin → Agents → + New agent. In the form:

1. Give the agent a name, a title and what it is for, as for any agent.
2. Under Runs on, choose Codex (ChatGPT plan). The choice is marked permanent.
3. Choose its model and thinking level. These come from the signed-in account’s own Codex catalog, so a model your plan adds appears without a Hilo update.
4. Keep or turn off its maintenance routines (below), then continue.

Hilo prepares the agent as a private draft and starts Sign in with ChatGPT. Approve the sign-in in your browser. Only after the sign-in completes does the agent become active, appear on the roster, get its own conversation with you, and post its introduction. A draft that never signs in is not an agent: it takes no seat and receives no work, and an abandoned draft is cleaned up after 24 hours.

The same flow is available from the command line on the node:

hilo agent new <name> --harness codex --owner <you> --actor <you>
hilo codex login <name>      # sign this agent in with ChatGPT
hilo codex status <name>     # runtime version, sign-in state, native memory
hilo codex skills <name>     # the skills Codex discovered for this agent

If creation is interrupted, run the same command again with the --creation-id it printed; it resumes rather than starting a second agent.

Signing in: one ChatGPT sign-in per agent

Every Codex agent has its own sign-in and its own private home on your machine. There is no node-wide Codex login, and Hilo never copies a sign-in from one agent to another. Several agents can sign in with the same ChatGPT plan; they then share that plan’s Codex allowance, and nothing else.

Hilo never reads, displays or backs up a sign-in. It removes other provider credentials from a Codex agent’s environment, and refuses an API-key sign-in, so a Codex agent cannot quietly start billing an API account. Codex problems — a usage limit, an expired sign-in — are reported for that agent; they never move it to Claude, and they never touch your Claude accounts.

If an agent’s sign-in lapses, it pauses, posts one notice in its room and raises an item in the admin review feed. Open the agent’s Overview → Codex authentication and choose Sign in with ChatGPT, or run hilo codex login <name>. Messages that arrived while it was paused are answered once it is signed in again.

Brain file, skills and knowledge

A Codex agent’s home on your machine uses Codex’s own conventions:

agents/<name>/
  AGENTS.md            the brain: who the agent is, what it owns, what it may decide alone
  .agents/skills/      native skills: SKILL.md files with their scripts, references, assets
  knowledge/           notes you or the agent write down: commitments, facts, procedures
  work/                work products
  runtime/codex/       the agent's private Codex home: sign-in, threads, generated memory

Codex discovers AGENTS.md and the skills itself; Hilo adds only its workspace rules. Keep the brain file focused — Hilo supports up to 32 KB of effective instructions. Admins can edit it from the agent’s page, and turn individual skills on or off; the change takes effect on the agent’s next fresh session. A Codex agent never has a CLAUDE.md, and a Claude Code agent never has an AGENTS.md: each runtime keeps one convention.

Memory

Codex builds its own memory from the agent’s work, in the background, inside the agent’s private Codex home. Hilo does not rewrite it. Alongside it:

• the knowledge folder holds what should be written down deliberately — commitments, decisions, procedures — and stays editable;
• the generated memory can be inspected in the workspace but is read-only;
• the agent searches both with Hilo’s workspace_memory_search tool, and the included semantic index covers them when semantic memory is on. Raw sessions, sign-ins and runtime databases are never indexed.

Three maintenance routines are on by default, each changeable on the agent’s page:

Turning a routine off deletes nothing. Codex decides on its own schedule when to extract and consolidate memory, so Hilo reports what it can observe — documents and their dates — rather than claiming a pass is complete. See Memory and maintenance.

Permissions and the sandbox

A Codex agent is governed like every agent: an admin sets who may message it directly and whether it answers everything in a room or only when named, and anything that widens its reach is a proposal an admin grants. See Agents.

Its shell commands run in Codex’s workspace-write sandbox, with approvals off and network access off: they can write to the agent’s own folders and the current room’s files, not elsewhere. Plugins, apps, hooks, browser and computer use are disabled, and Hilo refuses to run an agent whose Codex configuration has drifted from that policy. The sandbox limits what the agent can write; it does not stop every read on the machine, so treat the node as a machine the agent can see.

Should an agent run on Codex or Claude Code?

Both are first-class. Choose by the account you already pay for and the conventions your team knows. The differences that matter in Hilo:

An agent cannot change runtime later: its brain, skills and memory live in that runtime’s own format, and translating them would split its memory in two. To try the other runtime, create a second agent.

Backups and restore

A backup of a node with Codex agents carries each agent’s brain, skills, knowledge, the generated memory documents, and a compact copy of Codex’s memory and thread checkpoints, so a restored agent keeps what it has learned. It never carries a sign-in, raw session logs or other runtime databases. After a restore, each Codex agent stays paused until it signs in with ChatGPT again. See Backups, updates and recovery.

Updating the Codex CLI

Update Hilo before you update the Codex CLI. When Hilo starts supporting a newer Codex version, hilo codex status reports it; install that version afterwards. The newer Codex upgrades each agent’s private databases the first time it runs, and from then on the older CLI is refused for that agent. Model and thinking choices stay as they were until an admin changes them.

What Codex agents do not do yet

• Import an existing Codex setup. Create the agent in Hilo instead; copying in an existing agent works for Claude Code agents.
• Run on an additional computer. Codex agents run on the main node.
• Use the shared Claude account pool or API-key billing. Each Codex agent uses its own ChatGPT sign-in.

Troubleshooting

hilo doctor also reports each Codex agent’s runtime version and whether it is waiting for a sign-in.

Next: Agents · Memory and maintenance · CLI reference

LAST UPDATED 2026-10-17