Cloud sync: keep profiles, config, and settings across devices
Run CodexUse on more than one machine? Keep one primary setup and bring it to a second device in minutes. Push profiles, config.toml, and app settings from your main machine, then pull on the other. Every transfer is manual, available during trial and Pro, and backed up before each pull.
Best use case: one main machine, one secondary machine
Treat cloud sync as a setup handoff, not continuous background sync. 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 withcodexuse 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: runtime histories and workspace folders. 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 replaces local profiles, config, and settings with the remote snapshot.
- A green toast confirms "Cloud sync pull completed." Your profiles are now available.
CLI commands
Cloud sync also works from the terminal with the CodexUse CLI:
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.
- There is no granular merge. The entire snapshot (all profiles, full config, all settings) is replaced as a unit.
Pull behavior
- Before pulling, decide whether the remote snapshot should replace this machine's local state.
- After pull, profiles, config, and settings match the remote snapshot.
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 |
|---|---|---|
| "Cloud sync requires an active trial or Pro license" | No active trial or Pro license | Start an active trial or activate Pro 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 | Push a current snapshot from the correct machine, then pull again. |
What does CodexUse cloud sync actually sync?
Cloud sync transfers three things: your profile credentials, your config.toml content, and your CodexUse app settings. Runtime histories and workspace folders 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.