<!-- Source: https://console.uubright.com/docs/codex/ -->
# Codex host tasks

Run a Codex task using the official Codex CLI already configured on your server.
Codex uses the host account's existing Codex authentication and provider
configuration. It does not require CCR, a new API key or a hosted subscription.

## Server prerequisites

Install Codex CLI 0.163.0 or newer and authenticate it as the server user running
uuBright Console. The adapter is tested against 0.163.0's app-server protocol. Validate
model access independently before using the remote UI:

```sh
codex --version
codex login status
codex exec --skip-git-repo-check --sandbox read-only "Reply OK without tools"
```

Installation and a successful login-status check do not verify inference access.
If a standalone CLI turn times out or fails, fix that connection/account problem
on the server first. `CODEX_BIN` can select an explicit executable path. If an upgrade appears not to
apply, compare `type -a codex` and `npm prefix -g`: a login shell may use an NVM
installation while a service or non-interactive SSH uses `/usr/local/bin/codex`.
Exit old processes, pin the intended absolute path in `server.env`, and restart the
service when current tasks can safely reconnect. Reauthentication requires the
host user's interactive/device login; executable detection alone cannot do it.

## Create a task

Choose **Codex · server account** in New Task. The option is unavailable if a
supported CLI is not found in host mode. Create a scratch task first, then use a
repository. Tasks retain their own Git worktree and branch, transcript, changes
and pull-request controls.

Codex tasks can join [rooms](https://console.uubright.com/docs/rooms/) with a handle and can run as a
[lead or Manager](https://console.uubright.com/docs/lead/). The runner gives them `ccr-room`, `ccr-lead` when
they are leads, and `ccr-task` through Codex's `mcp_servers` configuration.
Room access stays scoped to that task's membership. A lead handed off from
Claude Code to Codex keeps its room handle, workers and workspace Manager role;
the old lead stops when the handoff succeeds.

**Ask for approval** uses Codex's `untrusted` policy with its workspace-write
sandbox. **Auto** uses `on-request` with that sandbox.

Codex's sandbox needs unprivileged user namespaces. Hosts that refuse them (Ubuntu
23.10 and later with AppArmor's default `kernel.apparmor_restrict_unprivileged_userns=1`,
many containers) can't start it, so Codex asks to run every command outside it. On
such a host you can set `CCR_CLOUD_CODEX_SANDBOX=danger-full-access` in `server.env`:
Codex tasks then run without Codex's sandbox, with the same access Claude host tasks
have (the server user's), and ask only where their approval policy says so. Existing
tasks pick the setting up when they resume. Leave it unset to keep the sandbox. These policies are Codex's
own rules: they do not reproduce Claude's permission behavior. Codex also asks before
each MCP tool call. uuBright Console supplies its own task, room and lead servers;
other MCP servers remain subject to your decision, shown with the server, the tool
and its arguments: **Allow once**, **Deny**,
or, where Codex offers it, **Allow for this task**, which lets Codex use that tool for the
rest of the task without asking again. Auto can still ask
for approval. Additional network or filesystem access is shown as an approval
request. Allow grants only the requested access for the current turn; Deny grants
none. Other Claude permission modes are unavailable for Codex tasks.
Concise response style adds a thread-level brevity instruction.

The selected agent is fixed for a task. Follow-ups go to its existing Codex thread;
Stop/Resume reuses the saved thread ID. The adapter does not replace `CODEX_HOME`,
write a new provider, or modify the user's authentication files. Threads remain
in the host's existing Codex state, so include that state in host backups.

## Custom model providers

A `[model_providers.<id>]` table in `~/.codex/config.toml` usually names its key with `env_key`, and may name
header values with `env_http_headers`; an MCP server may name variables with `env_vars` or
`bearer_token_env_var`. Codex reads those variables from its environment.

**On This Mac**, the uuBright Console service is started by macOS (launchd), which doesn't read your shell profile, so a
variable you set in `~/.zshrc` isn't in its environment. uuBright Console starts your own shell (`$SHELL`) the way VS Code
does, as an interactive login shell, so zsh reads `~/.zshrc`, bash `~/.bash_profile` (which usually reads
`~/.bashrc`) and fish its config. Its input is closed and it gets 4 seconds, so a prompt or theme can't hold it up.
From what it prints, uuBright Console keeps **only the variables your agent settings name**: those in your Codex config,
and `$VARIABLE`s in Claude Code's helper commands (`apiKeyHelper`, `awsAuthRefresh`, `awsCredentialExport`,
`otelHeadersHelper`). The values stay in the service's memory: they aren't written to the task's saved
environment, a log or the LaunchAgent. Each task gets only what **its own agent's** settings name: a Codex task
the names in its Codex config, a Claude task those in its Claude settings, and a workspace with its own login only
those in that login's home. PR reviewers get none.

Some names are never passed, whatever a config says: uuBright Console's own settings and tokens (`CCR_*`), Git and GitHub
credentials (`GH_*`, `GITHUB_*`, `GIT_*`, `SSH_*`), cloud keys (`AWS_*`, `AZURE_*`,
`GOOGLE_APPLICATION_CREDENTIALS`), and model credentials whose presence changes billing (`ANTHROPIC_*`,
`CLAUDE_CODE_*`, `CODEX_*`), plus the messaging tokens the service keeps from tasks. A variable that is only in
the service's own environment isn't passed this way either. The shell itself starts with a minimal environment
(`HOME`, `USER`, `PATH` and the like), so the service's settings don't reach anything your profile runs.

The configs and the shell are read when the service starts (**Restart uuBright Console** in the uuBright Console menu) and when you
refresh **Setup check**, never when a task starts, since a task could edit a config. On This Mac, tasks also
can't write `~/.codex/config.toml`, as with `~/.claude/settings.json`. Setup check has a **Shell environment**
line that names what was read and what is missing (never the values), and says when the shell couldn't be read;
then tasks get only their saved environment. The service log lists the same names.

If a key still isn't found, the task says which provider and variable: "Codex provider r9s needs
R9S_TEST_API_KEY. Set it in your shell profile and choose Restart uuBright Console." After restarting, **Resume** the
task (a running task keeps the environment it started with).

On a server, set such variables in the service's environment (`server.env`); tasks created afterwards get them.

### Before this fix (beta.5)

Until your Mac has a uuBright Console version with this change, put the variable in launchd's environment and restart
the service. In Terminal:

```sh
read -rs KEY && launchctl setenv R9S_TEST_API_KEY "$KEY" && unset KEY
launchctl kickstart -k "gui/$(id -u)/cloud.ccr.desktop.local"
```

`read -rs` keeps the key out of your shell history. Then start a **new** task or Manager: a task keeps the
environment saved when it was created, so an existing one still won't have the key. Caveats:

- `launchctl setenv` lasts until you log out or restart the Mac; run it again after that.
- Every app you open afterwards in this login session can read the variable, not only uuBright Console.
- `kickstart -k` restarts the service; running tasks keep running and reconnect, but the app may show
  **Reconnecting** for a few seconds.

## Continue a Codex thread

**New task → Continue a session…** lists the Codex threads whose working folder is the
project's checkout, one of its Git worktrees or a folder inside them, newest first, with
the title Codex gave them. Codex keeps every thread in `~/.codex/sessions` (or
`CODEX_HOME`), whichever client started it: the CLI, the IDE extension and the Codex
App all run through the same Codex app-server, so their threads are listed alike.
Archived threads (`~/.codex/archived_sessions`) aren't listed.

Picking a thread starts a Codex task that forks it with the app-server's `thread/fork`,
using the task's worktree as the working folder. The fork has its own thread ID, which
the task resumes after a Stop; the original thread is untouched and you can keep using
it in the CLI or the app. Only a workspace using the host's Codex login can continue
threads; see [Continue a session you started yourself](https://console.uubright.com/docs/tasks/#continue-a-session-you-started-yourself).

## Preview boundaries

- Host execution only. The Claude CCR route switcher and Docker Codex sessions are
  not implemented. An existing Codex provider configuration is preserved as-is.
- Structured Codex questions use the same answer form as Claude. Answers are
  translated back to Codex's original question IDs; they are distinct from tool
  approval. Secret-input questions and unknown formats are refused explicitly,
  with a request to use the CLI or ask in plain text. Never enter credentials in
  ordinary task chat.
- The normal test suite uses a fake app-server for approvals, follow-ups,
  interruption, resume and configuration preservation. Real model verification
  depends on the host's account and network; do not infer parity from executable
  detection alone.
- Codex and Claude have different sandboxes and approval semantics. Read each
  agent's own documentation before trusting a task with sensitive files.
