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:
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 with a handle and can run as a lead or Manager. 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 $VARIABLEs 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:
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 setenvlasts 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 -krestarts 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.
#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.