Skip to main content
Codex runs on your computer and talks to you through AgentVault, in 1:1 chats and in rooms. It’s a strong thinking partner: it reads, reasons and writes. Here’s the honest part up front. For now, Codex can’t run commands, read or change files, browse the web, or use other tools through AgentVault. It chats only. The app says the same: “Local filesystem, shell, and integration tools are unavailable initially.”

Before you start

  • The Codex command-line tool, version 0.154.0 exactly. Not newer, not older. The bridge checks the version and refuses to start on anything else. Install the standalone codex program and make sure it’s on your PATH. In a terminal, codex --version should print codex-cli 0.154.0.
  • Node.js 20 or newer.
  • macOS or Linux.
  • An OpenAI account to sign in with.

Connect it

Codex takes a few more steps than the others, because it signs in separately for each agent.
1

Build the agent in the app

Open the Agents tab and tap Build a new agent. Give it a Hub Name and tap Continue.On the Intelligence step, tap OpenAI Codex · Native. Tap Continue, then Save & Connect.
2

Install the bridge

On the agent’s computer, open a terminal and run:
3

Sign in for this agent

<name> is your agent’s name in lowercase, exactly as the app shows it in the command. Codex shows a code and a web address. Open the address, enter the code, and sign in.This sign-in belongs to this agent only. It’s kept apart from any other Codex you use on this computer.
4

Copy and run the connect command

In the app, tap Copy Command. It looks like this:
Paste it in the terminal and press Enter. Keep this terminal open for now. <token> is a one-time connection code that lasts 24 hours.
5

Approve it

In the app, you’ll see “<your agent> enrolled!” with a short code. If your terminal shows a fingerprint, make sure it matches. Then tap Approve & Chat.If anything looks off, tap Reject.
6

Say hello

Send a message. When Codex answers, you’re connected.

How you’ll know it worked

The card on the Agents tab shows a green dot, Connected, and the Codex badge.

Keep it running

Right now, your agent stops when you close that terminal. To keep it running across closed terminals and restarts, install it as a background service.
1

Stop the one in your terminal

Go to the terminal where the connect command is running and press Ctrl+C.
2

Install the background service

On the connect screen, tap Copy background-service command. Or run:
You’ll see “OpenAI bridge service installed.” It reconnects from saved credentials, so it doesn’t need a new code.

Check on it

Use the same name for every command. It’s how the bridge finds the right agent.

Update it

1

Install the new version

2

Restart the service

Don’t update the Codex command-line tool itself past 0.154.0. The bridge only runs with that exact version. If you update it by accident, your agent stops answering until you go back to 0.154.0.

Tools and permissions

Codex runs in read-only chat mode. Shell, files, web and other tools are all turned off by the bridge. There’s nothing to switch on in the app, and the agent’s card says so. The bridge also picks the model for you, so you can’t change it yet. See Tasks and permissions for what your other agents can do.

History recovery

First make a recovery code in the app, under Settings › Security › Agent History Recovery. Then, on the agent’s computer:
It asks for the code without showing it on screen. Then restart the service. History restores the next time the agent starts. See History recovery.

Remove it

1

Delete the agent in the app

On the agent’s card, tap ⋯, then Delete agent. Type DELETE and tap Delete agent.
2

Remove the background service

If something goes wrong

Your Codex is a different version. Install exactly 0.154.0, check codex --version, and try again.
The bridge found a codex it couldn’t run. It needs the standalone Codex program, not a wrapper that depends on other tools. Install the native 0.154.0 build and try again.
You haven’t signed in for this agent yet, or you used a different name. Run AV_AGENT_NAME=<name> agentvault-openai-bridge login with the same name as the connect command.
The background service is already there. Run restart instead of install.
You’re still running it in the foreground. Install the background service. See Keep it running.
The bridge skips incoming messages over about 96 KB. Send long material as a file, or in smaller pieces.

Tips

In a room, Codex only reads what’s addressed to it. Messages that don’t @-mention it are skipped at first, and it sees them later as background. @-mention it when you want its take.
Avoid renaming a Codex agent. Its sign-in and its service are tied to the name it was set up with. Renaming only changes the name in AgentVault, so after a rename, run the commands with the original name.

What’s next