Authentication

Codemux has an optional account system. Sign in to sync your settings across machines. The app works fully without an account — auth is only needed for cross-device sync.

The sign-in screen appears on first launch. It offers three ways forward:

Continue with ChatGPT — "Use your ChatGPT plan with Codex. No API key needed." This connects a ChatGPT plan to Codex, which is separate from your Codemux account and doesn't turn on sync. Once it's connected, Continue to CodeMux opens the app. You can manage the connection later under Settings → Agent.
Continue with GitHub, or email and password — "GitHub or email connects your CodeMux account for sync."
Continue locally with another provider — use Codemux without an account (settings won't sync). The choice is remembered, so the sign-in screen doesn't return on the next launch.

To sign in later from local mode, open Settings → Account and click Sign in for sync. While that screen is open, its button reads Back to workbench.

Creating an Account

Email and Password

On the sign-in screen, click "Don't have an account? Sign up"
Enter your name, email, and password — name is required, and the password needs at least 8 characters. The eye icon shows or hides the password.
Check your email for a verification link
After verifying, click I've verified my email and sign in with your email and password

Didn't get the email? Resend email on the Check your email screen sends another, then counts down 30 seconds before you can send again ("Sent. Check your inbox and spam folder."). The same button appears if you try to sign in before verifying ("Your email hasn't been verified yet."). If the server rate-limits you, you'll see "Too many requests. Wait a minute, then try again."

Forgot password? under the password field sends a reset link. It always reports "If that email exists, we sent a reset link.", so it never reveals whether an account exists.

GitHub OAuth

Click Continue with GitHub
Your system browser opens to authorize the Codemux app, and the screen switches to Waiting for GitHub — "Finish signing in in your browser."
After approval, the browser redirects to a local callback and you're signed in automatically

While waiting, Reopen browser starts the GitHub flow again (for a closed tab or the wrong account), and Cancel brings back the full sign-in form, email sign-in included. The wait times out after five minutes with "GitHub sign-in timed out. Try again." A sign-in you finish in the browser shortly after cancelling or timing out still goes through.

GitHub is the only OAuth provider currently supported.

What an Account Gives You

Two things sync across every machine you sign into:

Settings sync — Your personal settings (appearance, editor, terminal, git, notifications) roam with the account. Change a setting on your desktop and it's there on your laptop.
Skills sync — With the Agent Chat GUI enabled, your user-scoped skills under the supported provider roots sync server-side across your devices — no sync password, even for GitHub OAuth accounts. See Skills Sync for the full path list.

Cross-product compatibility: the same account works for both Codemux and Vexis. The shared codemux-api-* auth derivation is pinned in CI for both products.

What Stays Local

Not everything syncs. These stay on the current machine:

Workspace layouts and tab arrangements
Terminal presets
Project setup/teardown scripts
Sidebar state and UI preferences
Agent tool configuration

Your workspace state is stored in a local SQLite database, not on the server. The server only stores your settings and account info.

Session Handling

Once you sign in, you stay signed in. Sessions are long-lived — the token is stored encrypted on disk using AES-256-GCM with a machine-derived key.

Codemux re-verifies your session on launch and when the window regains focus (debounced to once per 5 minutes). If the token expires, you'll need to sign in again.

Offline Behavior

The app works fine without an internet connection:

Cached auth — If you've previously signed in, Codemux uses your cached credentials. All features work normally.
Settings changes — Saved locally with a dirty flag. They sync back to the server automatically when connectivity returns.
No account — Everything works except settings sync. No sign-in required.

Signing Out

Go to Settings → Account and click Sign out under Session. This clears your token and settings cache. Your local workspace state (layouts, projects, terminal history) is unaffected.

Privacy

On the server: Account info (email, name) and your synced settings
On your machine: Everything else — workspace state, terminal sessions, project data, browser history, all stored in local SQLite
Auth token: Encrypted on disk with a key derived from your machine ID, not stored in plaintext

On this page