Web Remote Access

Web Remote Access turns a running Codemux backend into a browser-accessible app. Turn it on in the desktop, or start it headlessly with codemux serve, then open its link on another device — a laptop, a phone on your Wi-Fi, or a browser anywhere on the internet. You get the same Codemux: the same projects, workspaces, terminals, agent chats, and git state, all backed by the same running instance.

It's a second screen for one backend, not a second app. The browser is just another window into the running instance. Close it and the agents keep going.

Default off in the GUI. Nothing is reachable until you turn it on in Settings → Remote Access or explicitly start codemux serve. Turning it off immediately disconnects every device.

Enabling it

Open Settings → Remote Access and flip the master toggle. The desktop starts a small web server on your machine (default port 4377). The settings pane then shows:

• Reachable at — a list of copy-ready links grouped by This device, Local network, and Tailscale, each with a security note. One is marked Recommended (the best "reach from anywhere" option).
• A pairing QR code and link with a live countdown to expiry.
• Your paired devices — name, platform, last-seen time, and a live-connection dot, each with a Revoke button.

Who can connect

The Access scope control decides which networks the server listens on:

• Everyone on my networks (all) — reachable from any LAN or Tailscale peer that has the address. The default.
• Tailscale only — reachable only over your Tailscale mesh (plus this machine). The port is never open on an untrusted LAN. Requires a connected Tailscale address.
• This device only (loopback) — reachable only from the same machine, e.g. after you tunnel in over SSH.

Changing the scope or port re-binds the server and drops any existing connections.

Running without a desktop GUI

codemux serve boots the full Codemux backend as a foreground web-remote server without opening a desktop window. It needs no display or Xvfb, making it useful on a home server, VPS, or a workstation reached only through SSH.

codemux serve
codemux serve --scope tailscale
codemux serve --scope loopback --port 4377
codemux serve --relay

The command uses the same projects, database, terminal persistence, pairing, access scopes, and web UI as desktop mode. It prints reachable links, a scannable pairing code, and then runs until Ctrl+C or SIGTERM. From another shell, run codemux remote pair to mint another code.

• --scope all|tailscale|loopback and --port have the same meaning as the Remote Access settings.
• --relay also attempts to enable the account relay for access outside your LAN or tailnet; relay access requires a signed-in, configured account.
• Only one Codemux backend can own a machine's state at a time. codemux serve refuses to start while the GUI or another server instance is running, and the GUI likewise refuses to start beside serve.

This is different from codemux-remote serve. codemux serve exposes the full Codemux application through a browser; codemux-remote is the smaller SSH-host compute daemon and MCP control plane used by remote-host workflows.

One-command bootstrap

On a fresh Linux box or VPS, two commands take you from nothing to a machine you can reach from anywhere:

curl -fsSL https://get.codemux.org/install.sh | sh
codemux connect

The installer is distro-aware. It uses the native package for the detected distro family (.deb / .rpm) so the system package manager resolves the WebKitGTK/GTK runtime dependencies, and falls back to extracting the AppImage payload — which ships its own copies of those libraries — everywhere else, including when the caller has no root.

codemux connect then does three things in order:

1. Signs you in. If the machine already has a session it says so; otherwise it runs the same flow as codemux login. It honors --email, and reads CODEMUX_PASSWORD from the environment for fully headless setup.
2. Writes the configuration — remote access on, relay mode on, plus any --scope and --port you passed. With nothing running it writes the config directly; with a GUI or codemux serve already running it drives the live instance over the control socket instead, so a running instance cannot clobber the write.
3. Installs a background service (only when nothing is already running) — a systemd user unit at ~/.config/systemd/user/codemux.service, enabled and started, followed by loginctl enable-linger.

Linger is what keeps the service running after you log out. If it is refused you get a warning and the setup still succeeds, but the service will stop when your session ends. If any earlier step fails, the unit is rolled back.

Re-running codemux connect is safe — it reports the steps already done rather than undoing them.

codemux connect status    # Account, config, service, running instance, registration
codemux connect off       # Remove the service and turn relay off — stays signed in

Relay mode is read from the persisted configuration rather than the unit file, so connect off changes behavior without rewriting the unit.

On a host with no systemd user bus — macOS, some containers — steps 1 and 2 still succeed and you are pointed at running codemux serve yourself.

Pairing a device

There are three ways to authorize a browser.

1. Scan or open a pairing link

In Settings → Remote Access, scan the QR code with your phone or open the link on the other device. Pairing tokens are single-use and expire after 10 minutes. Once paired, the browser stays authorized across refreshes until you revoke it.

2. Pair from the terminal

If you're SSH'd into the machine and don't want to open the GUI, run:

codemux remote pair
codemux remote pair --name "work laptop"

This prints a scannable QR code plus the pairing link, right in your terminal. Remote Access must already be enabled. The optional --name becomes the device's label in your paired-devices list.

3. Sign in with your Codemux account

If your desktop is signed into a Codemux account, turn on Account access in the Remote Access settings. A browser on the same network can then sign in with the same account instead of scanning a code — no pairing dance. The raw password never leaves the browser; the desktop confirms the sign-in belongs to its own account before allowing the connection.

Account-authorized devices start pending approval by default (a one-click circuit breaker on the desktop), even if you've turned pairing approval off. You can opt out with the "trust browsers on my account" setting.

Reach from anywhere (hosted client)

The methods above need the browser and Codemux instance to already share a network (Wi-Fi or Tailscale). The hosted client removes that requirement.

Turn on relay mode in Remote Access while signed into your Codemux account. Your Codemux instance registers itself with the device directory. Then, from any network:

1. Open app.codemux.org in a browser.
2. Sign in with GitHub (or email) — the same account your Codemux instance uses.
3. Pick your Codemux instance from the device list.
4. Codemux connects the browser straight to that instance and the full app loads.

The connection is end-to-end encrypted and peer-to-peer: your terminal keystrokes and agent output travel directly between the browser and your Codemux instance (hole-punched through NAT, or relayed as encrypted bytes when a direct path isn't possible). Codemux's servers help the two find each other but never see your data — no source code, terminal output, or agent traffic passes through them in readable form.

Relay mode is off by default — from-anywhere access is opt-in per machine, either from Remote Access settings or with codemux connect. The switch is Reach this device from any network, under From anywhere (relay).

Device registration

Once relay mode is on, the subsection reports whether the desktop actually registered itself:

• A Registered / Not registered yet badge.
• Registered as <name> and Address <node id>, both copyable.
• Last confirmed a relative time, and Last attempt failed: <error> when registration is failing.

Relay mode needs an account. If the desktop is signed out you're told exactly that: "This desktop isn't signed into a Codemux account, so it can't register for from-anywhere access."

What you'll see connecting

The hosted client walks through sign-in → device list → connecting:

• No devices yet — "None of your desktops are set up for remote access. On a desktop running Codemux, open Settings → Remote Access and turn on relay mode, then refresh this page."
• Waiting for approval — when approval mode is on, "Approve this browser on <device> to finish connecting."
• Device offline — "<device> isn't reachable right now — retrying…"

Signing in with email notes that "your password is stretched on this device and never sent as-is."

Approving and revoking devices

• Approval mode (optional) holds each new device pending until you approve it on the desktop. New pending devices raise a notification.
• Revoke a device at any time — its connection drops instantly and it can't reconnect. Revoke all clears every device.
• Turning the master toggle off disconnects everything at once.

Multiple devices at once

All connected clients — your desktop window and every browser — see the same state, including which workspace is active. Switch a workspace on your phone and it switches on the desktop too. A terminal or agent chat can be watched live from several devices at once.

What works in the browser

The browser client is the real Codemux UI, so nearly everything works as it does on the desktop, including:

• Live terminals with full input and scrollback
• Agent chat, including running turns and approvals
• Opening projects and creating workspaces (an in-app file picker replaces the native dialog)
• Notifications (delivered as browser notifications when your device allows them)
• Driving your configured remote hosts — a browser sees and controls them just like the desktop does

App updates stay on the desktop: it remains the single updater and won't restart itself while a remote device is connected.

Security notes

• Off by default, and disabling it severs every connection immediately.
• A connected device has full control of your desktop by design — it is your Codemux. Treat pairing like handing someone your keyboard. Revoke is instant.
• Secure browser features (clipboard, notifications) work over This device (loopback) and over HTTPS. On a plain-HTTP LAN address the browser may block them; the settings pane tells you which links are secure. For trusted HTTPS on the go, Tailscale's HTTPS serve or the hosted client is the recommended path.
• The pairing session is stored in the browser so it survives a refresh. On a shared machine, revoke from the desktop when you're done.

Relationship to remote hosts

Web Remote Access and remote hosts are complementary:

• Remote hosts move where the work runs — your desktop drives a workspace on another machine over SSH.
• Web Remote Access moves where you watch and steer it from — a browser drives a GUI or headless Codemux backend.

They compose cleanly: a paired browser automatically sees and controls whatever remote hosts your desktop has configured, with nothing extra to set up.