---
title: "Connect Codex to AI Gateway or an AI Agent | Hostman Docs"
description: "Learn how to install Codex CLI or Codex Desktop and connect it to Hostman AI Gateway or a custom AI agent using a simple TOML configuration file."
---

> For the complete documentation index for AI agents, see [llms.txt](https://hostman.com/llms.txt).

Codex is an AI coding assistant from OpenAI. It lets you work with your project directly from a desktop app or terminal—ask questions about your code, make changes, and run commands.

You can connect either an AI agent or an AI Gateway to Codex. With an AI agent, you work with a pre-configured agent setup; with AI Gateway, you call the model directly.

## Installing Codex

**Codex Desktop** is available for macOS and Windows. Download the installer for your OS from the [OpenAI website](https://openai.com/codex/get-started/).

**Codex CLI** can be installed on **macOS** or **Linux** with:

```shell
curl -fsSL https://chatgpt.com/codex/install.sh | sh
```

On **Windows**, use PowerShell:

```shell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
```

You can also install Codex CLI via a package manager:

#### npm

```shell
npm install -g @openai/codex
```

#### Homebrew

```shell
brew install --cask codex
```

## Connection Requirements 

Before configuring Codex, decide which connection type you'll use.

To connect an AI agent, you'll need:

-   [The agent's base URL](https://hostman.com/docs/ai-agents/api-usage/openai-compatible-api/#base-url)
-   [An API key](https://hostman.com/docs/ai-agents/manage-agents/api-access-key/)

To connect AI Gateway, you'll need:

-   Base URL: `https://ai-api.hostman.com/v1`
-   [An API key](https://hostman.com/docs/ai-agents/ai-gateway/connection/#creating-an-api-key)

## Configuring the Connection

All configuration lives in `~/.codex/config.toml`.

If you've used Codex before and want to preserve your existing setup, back up the current config first:

```shell
mv ~/.codex/config.toml ~/.codex/config.toml_old
```

Rename it back at any time to restore your previous settings.

Open or create the config file:

```shell
nano ~/.codex/config.toml
```

Add the following:

```shell
model_provider = "hostman"
model = "openai/gpt-5-mini"

[model_providers.hostman]
name = "Hostman"

base_url = "https://ai-api.hostman.com/v1"
env_key = "HOSTMAN_API_KEY"
```

Adjust the values to match your setup:

-   `base_url`: Use `https://ai-api.hostman.com/v1` for AI Gateway, or your agent's base URL if connecting an AI agent.
    
-   `model`: For AI Gateway, specify the model name (e.g. `openai/gpt-5-nano`); for an AI agent, use the model name from your agent settings. Check the [AI Gateway**AI Gateway Connection tab** tab](https://hostman.com/docs/ai-agents/ai-gateway/connection/#getting-connection-details) for the correct identifier.
    
-   `env_key`: The name of the environment variable that will hold your API key.
    
-   `name`: Optional; change the provider display name if needed.
    

Codex reads the API key from the environment variable specified in `env_key`. If your config uses `HOSTMAN_API_KEY`, set it with:

#### Linux

```shell
export HOSTMAN_API_KEY="your-api-key"
```

#### macOS

```shell
launchctl setenv HOSTMAN_API_KEY "your-api-key"
```

#### Windows

```shell
setx HOSTMAN_API_KEY "your-api-key"
```

Then start Codex:

```shell
codex
```

If you're using the desktop app, restart it to apply the changes.

The model you configured will be available in both Codex CLI and the Codex desktop app—in the desktop version, it appears directly in the chat window.