Skip to main content
CODEMUXManual

Web Remote Access

Drive a Codemux desktop or headless server from another browser — same projects, workspaces, terminals, and agent chats.

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 turn on the main switch. On its own that opens nothing — it's the kill switch for everything below it. Under Ways to connect, each way in has its own switch, its own settings, and its own live status:

  • From anywhere (Recommended) — any browser signed into your Codemux account, on any network, through app.codemux.org. No port is opened on this machine.
  • On my network — a small web server on this machine (default port 4377) for devices on the same network or tailnet, using a one-time pairing link.

Turn on either or both. They run independently: if the network server can't start, From anywhere still comes up. A box at the top always says, in one sentence, what your current setup actually exposes.

Upgrading from an earlier version? If you already had Remote Access on, On my network stays on.

On my network

When it's on, the card shows Listening on port N with the main address, plus:

  • Visible on — which networks the server listens on:
    • All networks (all) — every network interface. Anyone on your LAN or tailnet who has the address can reach it.
    • Tailscale only (tailscale) — only your Tailscale address (plus this machine). The port is never open on an untrusted LAN. Requires a connected Tailscale address.
    • This device only (loopback) — only 127.0.0.1, e.g. after you tunnel in over SSH.
  • Pair a device — see Pairing a device.
  • Reachable at — a collapsed list of copy-ready links grouped by This device, Local network, Tailscale, and Public internet, each with a security note. One is marked Recommended.
  • Port — changing it restarts the server and invalidates any open pairing link.

Changing Visible on or Port re-binds the server and drops browsers connected over your network. Browsers connected from anywhere aren't affected.

If the server can't start listening — the port is taken, or Tailscale isn't up yet — the card shows The server couldn't start listening with the real reason and a Retry button. Codemux keeps retrying in the background, and From anywhere is unaffected.

The same listener can also serve an HTTP MCP endpoint for outside assistants. That's a separate switch in Settings → MCP Servers, off by default.

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, and web UI as desktop mode. It prints reachable links and a scannable pairing code, then runs until Ctrl+C or SIGTERM. From another shell, run codemux remote pair to mint another code.

  • --scope all|tailscale|loopback and --port mean the same as Visible on and Port under On my network. Passing either one turns the network server on.
  • --relay turns on From anywhere before the network server starts, so a taken port no longer stops serve: it keeps running, reports LAN listener: not running — <reason>, and retries in the background. From anywhere requires a signed-in account.
  • A bare codemux serve keeps your saved setup. If the machine is set up relay-only (From anywhere on, On my network off), it stays relay-only: nothing listens on your network, no pairing code is printed, and you're pointed at app.codemux.org instead. Run codemux remote enable to also listen on your network.
  • 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, From anywhere on, plus any --scope and --port you passed. It also turns the network server on — unless the machine is already set up relay-only and you passed no --scope or --port, in which case it stays relay-only and reports relay only — nothing listens on your network. 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, and live listener / relay / registration state
codemux connect off       # Remove the service and turn From anywhere off — stays signed in

The From anywhere setting 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.

In Settings → Remote Access → On my network, click Create pairing link, then scan the QR code with your phone or open the link on the other device. Pairing links 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 and On my network must both be on. 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 Allow account sign-in instead of a pairing link in the On my network card. 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.

Browsers that sign in with your account start pending approval by default (a one-click circuit breaker on the desktop), even when pairing-link approval is off — and this applies to both ways in, including from anywhere. To let them connect right away, turn off Approve browsers that sign in with your account.

While a browser waits

A browser waiting for approval says so — "Approve this browser on the desktop app to finish connecting…" — and offers Cancel and use a different code. It stops waiting after 5 minutes. If it ends up back at the pairing form, a notice explains why: the desktop declined it, the wait timed out, or it's no longer paired. If reconnecting with a saved session is slow, Cancel appears after a few seconds.

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.

In Settings → Remote Access, turn on Remote Access and the From anywhere switch 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.

From anywhere is off by default — it's opt-in per machine, either in Settings or with codemux connect.

Device registration

Once From anywhere is on, its card reports whether the desktop actually listed itself with your account:

  • Registered, Registering…, or Not registered yet, with the device name (copyable) and when it was last confirmed.
  • Last attempt failed: <error> with a Retry button when registration is failing. Codemux also retries on its own, backing off up to every five minutes.
  • An Open app.codemux.org button, and the device's Address under Connection details.

Turning From anywhere off stops registration right away; the device simply stops showing as recently seen. It 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 — browsers signed in with your account wait for approval by default, "Approve this browser on <device> to finish connecting."
  • Device offline — "<device> isn't reachable right now — retrying…"
  • Gave up — if the connection isn't set up within 30 seconds (or approval doesn't arrive within 5 minutes), the page stops, shows the error with its underlying reason, and offers Back to devices so you can pick another device or retry. Once connected, a dropped session still reconnects on its own.

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

Approving and revoking browsers

  • When a browser asks to connect, the desktop shows a "<browser> wants to connect" toast with Approve and Reject — wherever you are in the app, not just in Settings. The toast stays up until the request is answered (from the toast or from Settings).
  • In Settings → Remote Access, waiting browsers also appear under Paired browsers → Waiting for approval. Browsers that sign in with your account wait there by default (Approve browsers that sign in with your account). Browsers using a pairing link only wait when Approve browsers that use a pairing link is on (off by default).
  • Paired browsers lists everything that can reach this machine, from either way in, tagged Paired or Account with a Connected/Offline indicator. Revoke drops a browser instantly and it can't reconnect; Revoke all clears every one after you confirm.
  • Turning On my network or From anywhere off disconnects only the browsers using that way in. Turning the main switch off disconnects everything at once.

Paired browsers are separate from Settings → Devices, which is where you add the SSH machines Codemux can run threads on.

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.

Dynamic workflows can't be started from a browser; use the desktop for those.

On a phone

Below 768 px wide, the browser client switches to a phone layout:

  • Long chats open at the latest message.
  • Chips above the composer — for example 1 file +9 −1 and #172 — open the changed files and the pull request directly.
  • The ⋯ button in the header opens the workspace's tools; each tool panel has a single header row.
  • Terminals show one pane at a time, without split buttons, and desktop-only hints such as Ctrl+Enter to send in background are hidden.
  • Copy under each message is icon-only; touch shows message actions without hovering.

Security notes

  • Off by default, and disabling it severs every connection immediately. Turning Remote Access on opens nothing until you also turn on a way to connect.
  • 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 (see the Devices page) 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.