Home › Docs › Settings & config

Settings & config

ReferenceUpdated Aug 2026 · 4 min read

Control how CodexUse and Codex App windows behave: Codex App orchestration on the Rotation tab, Account Pool, auto-roll, Cloud Sync, and updates. Codex’s own settings stay in config.toml, one per profile, and you edit that file by hand.

What is in Settings

The Settings screen holds four rows:

Preferences

Theme, usage display, and close behavior.

CodexUse CLI

Install state and status for the optional codexuse-cli.

Support

Diagnostics you can copy when you report a problem.

Features

Opens the feature catalog.

Accounts Pool, Telegram, Cloud Sync, and Model Providers live under Connect, not Settings.

Codex Apps

Use the Rotation tab to orchestrate Codex App windows by saved profile. CodexUse can detect profile-matched windows, show running state, uptime, PID, and app-server PID, then focus, stop, restart, or launch the selected profile window.

Model Providers

Model Providers is a Connect tab, not a Settings row. Run models from OpenRouter, DeepSeek, Groq, or your own Mac inside the Codex App. Add a connection with a vendor name, base URL, and credential; publish the models you want; then bind a profile to that connection. The credential stays in the macOS Keychain and is never written into config.toml.

Codex config (config.toml)

Codex keeps its own settings in config.toml. CodexUse does not provide an editor for it: you open the file and edit it by hand. What CodexUse does provide is separation — each profile has its own Codex home, so each profile has its own config.toml.

Model defaults

Model, review model, and reasoning defaults.

Approvals

How much Codex asks before it acts.

Sandbox mode

Read-only, workspace-write, or full access for shell and file actions.

Codex’s own documentation is the reference for the exact keys. See MCP, skills, and AGENTS.md for the MCP server blocks.

Notifications

In-app status signals track long-running sessions so you do not have to watch them.

Tip: keep the dashboard visible during long-running tasks to avoid manual polling.

AGENTS.md

Write persistent agent instructions once and reuse them across sessions.

A global AGENTS.md for shared Codex guidance.
Workspace-level overrides when a project needs them.
Keep instructions short and actionable.

Cloud Sync Pro

Move your profiles, config.toml, and app settings between devices with manual push and pull. Nothing syncs in the background. Typical flow: push from your main machine, then pull on the second one.

What syncs

Profile credentials, config.toml content, and CodexUse settings. Codex App conversations stay local.

Push & Pull

Go to Connect → Cloud Sync and click Push or Pull. Or use codexuse sync push / codexuse sync pull from the CLI on any machine where you installed codexuse-cli.

Pull behavior

Pull replaces local profiles, config, and settings with the remote snapshot.

Note: Cloud sync is manual and needs an active trial or Pro. Nothing syncs without your action. Conflicts use last-writer-wins — if your push is older than the remote, you will be asked to pull first.

Example: keep your main setup on a MacBook, then run codexuse sync pull on another machine with the CLI installed to start with the same profiles and config.

For a full walkthrough, see the cloud sync guide.

Accounts Pool Pro

Expose selected Codex accounts behind one local OpenAI-compatible endpoint. Accounts Pool publishes /v1/models, accepts /v1/responses and /v1/chat/completions, generates local API keys, and keeps a pooled session alive by rolling over to another eligible account when one runs into trouble.

Endpoint

Copy the base URL from Connect → Account Pool and hand that exact local endpoint to the client that should use the pool.

Routing

Choose least-used or round-robin for new pooled sessions, while CodexUse keeps continuity for ongoing pooled work.

Published models

Expose only the base models and alias variants you actually want local clients to see.

Start here: read the Accounts Pool docs for setup, routing, and failover details, then use the client setup guide if you are wiring another OpenAI-compatible tool into the pool.

You can manage the same pool from the CLI too: codexuse account-pool status, codexuse account-pool profiles set ..., and codexuse account-pool keys create for the desktop runtime. The settings, API keys, and pooled sessions belong to the desktop app runtime store.

Updates

Current desktop releases target macOS on Apple Silicon. Those builds can check for updates and install new releases in-app when available.

Manual upgrade path: If you are on CodexUse 2.5.8 or older, redownload the current app manually once and replace the old install. Intel Mac and Linux desktop builds are not shipped in the current release line.

Themes

Two theme modes are available: Dark and Light. Each theme defines a comprehensive surface palette covering every UI element. The app can follow your system preference automatically.

Dark

Deep surfaces with transparency layers. Designed for low-light environments and extended sessions.

Light

Clean surfaces with slate undertones. Designed for well-lit rooms and daytime use.