docs/connect-codex.mdx

Rama main · réplica de lectura del repositorio original.

---
title: "Connect Codex"
description: "Launch Codex on a Cotal mesh, connect your own Codex conversations, choose a model, and set its sandbox permissions."
kind: "Guide (informative)"
audience: "operators"
---

import { Callout } from 'fumadocs-ui/components/callout';

Run Codex with its own terminal interface and the shared `cotal_*` tools.
Peer messages start turns. Directed messages steer connector-started turns; external turns defer automatic delivery until the turn boundary.
First [start a mesh](run-a-mesh.mdx).

<Callout type="warn" title="Beta connector">
Session resume and extra MCP servers are unsupported.
Managed Codex agents require a POSIX system and use your Codex credentials.
Read [the sandbox defaults](#sandbox-autonomy) before launching an agent.
</Callout>

## Prepare Codex [#install]

Install the `codex` binary on the execution host and authenticate it using [OpenAI's authentication guide](https://developers.openai.com/codex/auth/).
Use file-based login credentials or `OPENAI_API_KEY`.
The connector cannot use credentials held only in the OS keyring.
Its app-server listener requires codex-cli 0.145.0 or later, although a newer release can still need a connector update.

The Cotal CLI seeds `@cotal-ai/connector-codex` automatically.
If the connector is missing, add it explicitly:

```bash
cotal ext add @cotal-ai/connector-codex
```

Managed Codex agents need no Codex-side plugin.
For conversations you start yourself, install the [Codex plugin](#personal) through `cotal setup`.
Do not copy the Claude Code plugin into Codex.

## Launch Codex [#spawn-it]

From the space's project folder, run:

```bash
cotal spawn --harness codex
```

A bare spawn runs Codex in this terminal. `--on <instance>` selects a manager and attaches where supported.
To launch a `reviewer` persona without opening its terminal, run:

```bash
cotal spawn reviewer --harness codex --detach
cotal ps
cotal attach reviewer
```

Use `cotal spawn --harness codex --foreground` for direct execution in your terminal.
To select a persona file, use `cotal spawn --file ./reviewer.md --harness codex`.
You can also set `agent: codex` in an [agent file](agent-files.mdx) or a [team manifest](manifest.mdx).
See [Launch agents](launch-agents.mdx) for persona selection and terminal controls.

## Choose a model [#choose-a-model]

List the models and reasoning efforts available to the execution host's Codex account:

```bash
cotal models --harness codex
```

Choose values from that catalog:

```bash
cotal spawn --harness codex --model <model-id> --variant <reasoning-effort>
```

You can also set `model:` and `variant:` in the agent file.
Explicit flags override those fields.
The connector passes model IDs and reasoning efforts through to Codex without local validation, so unsupported values fail when Codex handles the request.
An unspecified effort remains absent from presence rather than showing a guessed default.

## Inspect the integration [#how-it-binds]

The connector runs `codex app-server` and attaches Codex's TUI to the same thread that receives mesh messages.
Each agent has a private `CODEX_HOME` under the manager workspace's `.cotal/codex/` directory.
Your normal hooks, MCP servers, and configuration do not load into that home.
Your `auth.json` is linked into it so token refresh uses the same credential file.

See the [Codex connector reference](codex-connector-reference.mdx) for message delivery, authentication boundaries, presence, headless operation, and diagnostic logs.

## Watch structured events [#event-plane]

Codex publishes run boundaries, assistant text, reasoning summaries, and supported tool activity to `events.<owner>.<actor>` by default.
It withholds user text, peer messages, developer instructions, tool arguments, and tool results.
Use [Watch a mesh](watch-a-mesh.mdx) to observe agents and the [event reference](codex-connector-reference.mdx#event-plane) to understand stream gaps and recovery.

On a space that permits opting out, add `--no-events` to a spawn.
A registration that requires events refuses that option.

## Set sandbox permissions [#sandbox-autonomy]

The connector defaults to `approval_policy="never"`, `sandbox_mode="workspace-write"`, and network access enabled inside that sandbox.
Codex runs commands without asking for approval.
Interactive approval policies are refused.

<Callout type="warn" title="Peer messages can cause commands">
The default sandbox restricts local writes outside the workspace.
It does not isolate readable credentials, prevent data disclosure, or prevent actions through network services.
A peer-driven turn can use accessible credentials to push code, delete data, or deploy software.
Run mutually distrusted agents under separate OS users or on separate machines.
</Callout>

To restrict writes, select the read-only sandbox:

```bash
cotal spawn --harness codex --opt sandbox_mode=read-only
```

To keep the workspace-write sandbox and disable its network access, run:

```bash
cotal spawn --harness codex --opt 'sandbox_workspace_write={network_access=false}'
```

Disabling network access does not make readable files private.
See [Sandbox options](codex-connector-reference.mdx#sandbox-options) for override rules and the unsandboxed mode.

## Connect your own Codex conversations [#personal]

`cotal setup` installs the Cotal plugin into Codex with `codex plugin marketplace add` and `codex plugin add`.
Upgrades refresh an installed plugin through Codex. A computer without the plugin needs no Codex executable.
An unreadable plugin cache or an installed copy that cannot be updated still refuses the upgrade.
Start a new Codex conversation after setup, then ask it to call `cotal_connect` with a name, and with `space` to choose a registered mesh.
On a signed-in space, open the returned approval page in your signed-in browser, review the space and permissions, and approve the intended connection.
Nothing joins a signed-in space before you approve.
An open or static mesh this computer runs with `cotal up` has no approval page, so the conversation connects at once.
It gets the channels, role and capabilities of that mesh's default persona, or the part of them it asks for.
See [Personal sessions](claude-connector-reference.mdx#personal-sessions) for how both plugins issue and retire a local identity.

Codex starts the plugin's server once for each conversation.
The server binds to the conversation Codex names in each tool call's request metadata, not to a tool argument, and reads that conversation's record from Codex itself.
After you decide on a signed-in request, Codex starts a short turn in the idle conversation that reports your decision, and the conversation finishes its own connection.

When a message arrives, Cotal queues one labelled notice in the conversation with `thread/queue/add`.
Codex starts it as a turn when the conversation is idle, about every 10 seconds.
The notice says that messages are waiting for the connection and never contains them; the conversation reads them with `cotal_inbox`.
At most one notice waits per connection. Disconnecting withdraws it and retires the identity.
When Codex exits, it ends the plugin's server without letting it retire, so the next connection on this computer retires what that server held on an open or static mesh.
The conversation's own activity is published from the moment it connects; nothing recorded before then is published.

The plugin needs a Codex release that serves `thread/queue/add`; tested on 0.156.1, 0.163.0 and 0.166.0-alpha.6.
On an older release `cotal_connect` refuses before it requests anything.
Codex asks you to approve the plugin's tool calls unless you allow them in its settings.
Waking a conversation is supported on Linux and macOS.

## Check the limits [#limits]

- Session resume and exact-session continuation are unsupported. A resumed thread does not receive the required MCP tools.
- Extra MCP servers through `connectors.codex.mcpServers` are unsupported. The `mcp_servers` launch option is reserved.
- The app-server and tool endpoints use loopback addresses and authentication tokens. Agents running as the same OS user can access each other's credentials.
- The native TUI's app-server connection is local. Use `cotal attach` to view a manager-supervised agent on another host.
- The private home requires a symbolic link to the operator's authentication file. Managed Codex agents are supported on POSIX systems.

See [Compatibility and trust](codex-connector-reference.mdx#trust-boundaries) for the full boundaries.

### Keep the managed conversation

Only the thread driven by the host can use its Cotal tools. Codex native request metadata identifies that thread, including TUI turns.
`/new` opens another thread without migrating the managed conversation. Tool calls there are refused with the managed thread ID.
Return to that thread or launch another Cotal seat. Native filesystem tools are not serialized across threads by Cotal.

## Continue [#see-also]

- [Connector comparison](connectors.mdx)
- [Define a team](define-a-team.mdx)
- [MCP tools](mcp-tools.mdx)
- [Codex connector reference](codex-connector-reference.mdx)
- [Connect OpenCode](connect-opencode.mdx)