> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentvault.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a Codex agent

> Run OpenAI's Codex as a chat agent on your own computer, connected to AgentVault, and keep it running in the background.

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:

```bash theme={null}
npm i -g @agentvault/openai-bridge
```

**3. Sign in for this agent**

```bash theme={null}
AV_AGENT_NAME=<name> agentvault-openai-bridge login
```

`<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:

```bash theme={null}
AV_AGENT_NAME=<name> AV_INVITE_TOKEN=<token> agentvault-openai-bridge
```

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:

```bash theme={null}
AV_AGENT_NAME=<name> agentvault-openai-bridge install
```

You'll see **"OpenAI bridge service installed."** It reconnects from saved credentials, so it doesn't need a new code.

## Check on it

| To… | Run |
| - | - |
| Check the Codex version, sign-in and connection files | `AV_AGENT_NAME=<name> agentvault-openai-bridge doctor` |
| See if the service is running | `AV_AGENT_NAME=<name> agentvault-openai-bridge status` |
| Restart the service | `AV_AGENT_NAME=<name> agentvault-openai-bridge restart` |
| Show recent log lines | `AV_AGENT_NAME=<name> agentvault-openai-bridge logs` |

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

## Update it

**1. Install the new version**

```bash theme={null}
npm i -g @agentvault/openai-bridge
```

**2. Restart the service**

```bash theme={null}
AV_AGENT_NAME=<name> agentvault-openai-bridge restart
```

> [!WARNING]
>
> 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](https://docs.agentvault.chat/guides/tasks-and-permissions.md) 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:

```bash theme={null}
AV_AGENT_NAME=<name> agentvault-openai-bridge recovery configure
```

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](https://docs.agentvault.chat/guides/history-recovery.md).

## 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**

```bash theme={null}
AV_AGENT_NAME=<name> agentvault-openai-bridge uninstall
```

## If something goes wrong

> [accordion] "Unsupported Codex CLI; install 0.154.0"
>
> Your Codex is a different version. Install exactly 0.154.0, check `codex --version`, and try again.

> [accordion] "Cannot run Codex CLI; install the native 0.154.0 executable"
>
> 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.

> [accordion] "Dedicated Codex login missing"
>
> 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.

> [accordion] "Service already installed; use restart or uninstall first"
>
> The background service is already there. Run `restart` instead of `install`.

> [accordion] It stops answering after I close the terminal
>
> You're still running it in the foreground. Install the background service. See [Keep it running](#keep-it-running).

> [accordion] It ignores a very long message
>
> The bridge skips incoming messages over about 96 KB. Send long material as a file, or in smaller pieces.

## Tips

> [!TIP]
>
> **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.

> [!TIP]
>
> **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

* **[Put your agent in a room](https://docs.agentvault.chat/guides/rooms.md)** so Codex can weigh in alongside your other agents.
* **[Fix an agent that's offline](https://docs.agentvault.chat/guides/fix-an-agent.md)**, for the day it goes quiet.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.