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

# Codex

> Run OpenAI Codex agents in Replicas workspaces.

Replicas runs [Codex](https://developers.openai.com/codex/) inside isolated workspace VMs, with access to your repository, environment configuration, and integrations.

## Setup

Choose one authentication method:

* **OpenAI OAuth:** Run `replicas codex-auth` to connect an existing ChatGPT subscription.
* **OpenAI API key:** Add a key under [Organization → Coding Agents](https://tryreplicas.com/dashboard/agents).
* **Microsoft Foundry:** Add an Azure OpenAI API key, base URL, and model deployment under [Organization → Coding Agents](https://tryreplicas.com/dashboard/agents).

Pass `--user` to `replicas codex-auth` to save OAuth credentials to your account instead of sharing them with the organization. Personal credentials take priority over organization defaults. See [Credentials](/admin/credentials) for details.

## Models

Replicas supports the current GPT coding model family exposed in the workspace model picker. Set the organization default under [Organization → Settings → Preferences](https://tryreplicas.com/dashboard/settings?tab=defaults), or choose a model for an individual chat.

The available models depend on the connected OpenAI account and its model access.

## Using Codex in Workspaces

In a workspace, use the composer's harness/model picker to choose **Codex** and start or continue a session. Codex can:

* Read and edit files and run shell commands
* Use environment [skills and supported MCP servers](/features/environments#mcps)
* Create branches, commits, and pull requests
* Accept messages steered into an active turn
* Use [Plan Mode](/features/workspaces/plan-mode) and [Fast Mode](/features/workspaces/fast-mode)

### Goal Mode

Use `/goal <objective>` to give the thread a persistent objective. Pause, resume, or remove it with `/goal pause`, `/goal resume`, or `/goal clear`. The active goal appears above the composer and on the chat tab.

### Thinking levels

Use **Ultra** in the thinking picker for Codex models that support the `ultra` reasoning effort.

### Chat history

Codex sessions persist across turns and workspace sleep. Codex compacts its context automatically when needed. Use `replicas read` from the [CLI](/features/cli) to inspect transcript history.

## Programmatic Use

Select Codex anywhere Replicas accepts a coding agent:

| Surface                                                                                                      | How to choose Codex                                                      |
| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| [CLI](/features/cli)                                                                                         | `-a codex` on `replicas create` and `replicas send`                      |
| [API](/features/api)                                                                                         | `"coding_agent": "codex"` on create and message requests                 |
| [MCP](/features/mcp)                                                                                         | `"coding_agent": "codex"` on `create_replica` and `send_replica_message` |
| [Automations](/features/automations)                                                                         | Set **Coding agent** to Codex                                            |
| [Slack](/features/slack), [Linear](/features/linear), [GitHub](/features/github), [GitLab](/features/gitlab) | Set Codex as the [default coding agent](/admin/defaults)                 |

```bash theme={null}
replicas create fix-api \
  -e backend \
  -a codex \
  -m "Fix the failing API integration"
```

## When to Use Codex

Codex is a strong fit when you want OpenAI-native coding models, steerable active turns, or a persistent goal for longer work. Use Claude Code when you need Claude background tasks; use Cursor or Opencode when you prefer their model and authentication ecosystems.