Cloud Sync Last reviewed: 2026-02-13 Tested with CodexUse 2.4.4 + bundled Codex CLI 0.101.0 ~6 min read

Cloud sync: keep profiles, config, and settings across devices

If you use CodexUse on more than one machine, cloud sync lets you keep one primary setup and bring it to another device in minutes. Push profiles, config.toml, and app settings from your main machine, then pull on the second machine. Everything is manual, Pro-only, and backed up before every pull.

Key takeaway: Cloud sync is a manual push/pull for Pro users. It transfers profile credentials, config.toml, and app settings between machines so a second device can feel ready fast. Sessions and chat history stay local.

Best use case: one main machine, one secondary machine

Most users treat cloud sync as setup handoff, not continuous background sync. Example: keep your day-to-day setup on a MacBook, then pull it onto a Linux box before a coding session.

On your main machine, finish profile login and config changes.
Push once from Settings → Cloud Sync (or run codexuse sync push).
On the second machine, run codexuse sync pull, then verify with codexuse profile list.

What gets synced

Profile credentials — account auth state and metadata for every profile you have added.
config.toml — your Codex CLI configuration (models, approval policy, sandbox mode, MCP servers).
App settings — CodexUse preferences like auto-roll thresholds, notification settings, and UI state.

What stays local: sessions, chat history, project folders, and analytics data. Cloud sync does not touch those.

How to push from the desktop app

Open CodexUse and go to Settings → Cloud Sync.
Verify your license state shows active.
Click Push to cloud.
A green toast confirms "Cloud sync push completed." The remote snapshot timestamp updates.

How to pull on another device

Open CodexUse on the second machine and activate your Pro license.
Go to Settings → Cloud Sync and click Pull from cloud.
CodexUse creates a pre-pull backup, then replaces local profiles, config, and settings with the remote snapshot.
A green toast confirms "Cloud sync pull completed." Your profiles are now available.

Heads up: Pull replaces your local data with the remote snapshot. CodexUse automatically creates a local pre-pull backup and keeps the latest 3 backups.

CLI commands

Cloud sync also works from the terminal with the CodexUse CLI:

# check sync status

codexuse sync status

# push local state to cloud

codexuse sync push

# pull remote snapshot to this machine

codexuse sync pull

How conflicts are handled

Cloud sync uses last-writer-wins based on timestamps.
If you push and the remote snapshot is newer than your local data, the push is rejected with a "Pull first" message.
Pull always overwrites local data with the remote snapshot. A pre-pull backup is created automatically.
There is no granular merge. The entire snapshot (all profiles, full config, all settings) is replaced as a unit.

Pre-pull backups

Before every pull, CodexUse saves your current local state to an automatic local pre-pull backup.
The latest 3 backups are kept. Older backups are pruned automatically.
If the backup fails (disk full, permissions), the pull still continues. A warning is shown in the result message.

Snapshot size limits

Snapshots above 1 MB trigger a warning log.
Snapshots above 5 MB are rejected with a clear error message.
If you hit the limit, reduce the number of profiles or trim your config.toml.

Troubleshooting table

Symptom	Likely cause	Action
"License key is required"	No Pro license activated	Activate your Pro license in Settings → License.
"Remote cloud snapshot is newer. Pull first."	Another device pushed a newer snapshot	Pull first to get the latest state, then push again.
"Snapshot too large to sync"	Combined profiles + config exceeds 5 MB	Remove unused profiles or trim config.toml.
"Cloud sync request timed out"	Network issue or server unavailable	Check your internet connection and try again.
Pull succeeded but profiles look wrong	Remote snapshot was outdated	Open your recent local pre-pull backups and restore if needed.

What does CodexUse cloud sync actually sync?

Cloud sync transfers three things: your profile credentials, your config.toml content, and your CodexUse app settings. Sessions, projects, and chat history stay local.

Does cloud sync run automatically in the background?

No. Cloud sync is manual. You explicitly click Push or Pull in Settings, or run codexuse sync push / codexuse sync pull from the CLI. Nothing syncs without your action.

What happens if I pull and my local data is newer?

Pull always replaces local data with the remote snapshot. CodexUse creates an automatic local pre-pull backup so you can recover, and keeps the latest three backups.

Download CodexUse - free (2 profiles, 2 projects)