Home › Docs › Settings & config

Settings & config

Control how CodexUse and Codex CLI behave: Accounts Pool, models, approvals, sandbox mode, and config.toml.

Last updated: 2026-04-03 Settings Current desktop

Settings layout

In 2.5.0, settings are organized into three groups:

Codex

Core settings, MCP servers, and Skills.

Chat

Projects, Environments, Display & Sound, Composer, Shortcuts, Open In, Git.

CodexUse

Accounts Pool, Auto-roll, CLI, Cloud Sync, Telegram remote.

config.toml editor

Edit Codex CLI config without hand-editing files. Use presets or paste your own.

Model defaults

Set chat + review models and reasoning levels.

Approvals

Choose manual or auto approvals for actions.

Sandbox mode

Pick safe defaults for shell + file actions.

Notifications

Use in-app status signals to monitor long-running sessions.

Tip: Keep the dashboard visible for long-running tasks to avoid manual polling.

AGENTS.md

Write persistent agent instructions once and reuse them across sessions.

Global AGENTS.md for all projects.
Project-level overrides when needed.
Keep instructions short and actionable.

Cloud Sync Pro

Sync your profiles, config.toml, and app settings across devices with manual push and pull. Typical flow: push from your main machine, then pull on your second machine.

What syncs

Profile credentials, config.toml content, and CodexUse settings. Sessions and chat history stay local.

Push & Pull

Go to Settings → 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.

Pre-pull backups

Before every pull, CodexUse creates an automatic local pre-pull backup (latest 3 retained).

Note: Cloud sync is manual and Pro-only. 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, generates local API keys, and can keep a pooled session alive by rolling over to another eligible account when needed.

Endpoint

Copy the base URL from Settings 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 ..., codexuse account-pool keys create for the desktop runtime, and codexuse account-pool keys create --runtime=daemon for a headless daemon. The settings are shared; API keys and pooled sessions stay runtime-specific.

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.

Tip: Enable reduced transparency in Settings for more opaque surfaces, helpful for screen sharing or visual accessibility.

See the themes guide.

Telegram remote control Pro

Connect a private Telegram bot to CodexUse and control your workspace from your phone.

Approve exec and apply-patch requests from Telegram.
Send prompts and switch projects remotely.
Check session status and rate-limit headroom.
Get notified when turns complete or error out.

Setup: create a bot via @BotFather, paste the token in Settings → Telegram, and enable the bridge. See the Telegram guide for a full walkthrough.

You can also run the headless server via the CLI and add Telegram on top: codexuse daemon start --port=3773 --telegram-bot-token=<token>. The same daemon can host Accounts Pool for other local clients. See CLI reference.

Notification sounds

CodexUse 2.5 plays audio alerts:

Success sound: Plays when a task or long-running turn completes.
Error sound: Plays when a turn fails.
Volume is normalized (gain: 0.05) using the Web Audio API.
Test sounds from Settings → Display & Sound.

System notifications also fire when a chat needs your response or a turn completes.

Integrated terminal

A terminal dock at the bottom of the desktop layout with full PTY sessions.

Multiple tabs — create, switch, close.
Drag the separator to resize.
Powered by node-pty (real PTY) and xterm.js (rendering).
Inherits your default shell and environment.

For details, see the terminal guide.