Remote

Pair with another Clauge desktop and control its Agent, SSH, Files, Terminal, and Browser from your phone or from a second computer.

Remote turns any paired device into a control surface for a Clauge desktop. Once paired, the connecting device can start and monitor Agent sessions, browse and edit files, open SSH or Terminal sessions, use Browser mode, and view live status of running projects.

It works over your local network or over a tailnet if one is configured. No data leaves your network unless remote access is explicitly enabled for a host.

How it works

Every Remote connection has two roles:

• Host — the desktop being controlled. It enables the remote access server and approves incoming devices.
• Client — the phone or desktop that connects to and controls the host.

Pairing always needs both sides. The client submits a host address and a one-time code; the host must have generated that code (or manually approve the device) before a connection is established.

Before you start

• The host machine must be running Clauge desktop.
• The host and client must be reachable on the same network, or connected via a tailnet.
• Remote access must be enabled on the host: Settings → Remote Access → Enable remote access.

Install the mobile app

On the phone or tablet you want to pair:

1. On the host desktop, open Settings → Remote Access.
2. Under Get the app, scan the QR code for your platform (Android or iOS), or open the download link directly.
3. Install and open the app on your device.

If you’re pairing a second desktop instead of a phone, skip this step — Clauge desktop already includes Remote mode.

Enable remote access on the host

Before any device can connect, the host must expose itself on the network:

1. On the host, open Settings → Remote Access.
2. Turn Enable remote access on.
3. Once enabled, the host shows the address it’s reachable at under Running at (for example 10.124.58.76:7431).

Remote access stays off by default. Turning it off at any time stops the host from accepting new connections.

Pair a device

You can pair by generating a code on the host (recommended), or by entering connection details manually from the client.

Generate a code on the host

1. On the host, go to Settings → Remote Access → Add device.
2. Click Generate code. The host shows a QR code, a 6-digit pairing code, an expiry countdown (codes expire after 2 minutes), and the address it’s reachable at.
3. On the client:
   • Mobile app — open Add device, tap Scan QR, and scan the code on the host. Or enter Host, Port, and Code manually on the same screen.
   • Second desktop — open Remote → Add Device, enter the Host, Port, and Pairing code from the host, optionally set a Device name, then click Pair.
4. Approve the request on the host. Once approved, the device appears under Connected devices.

Enter details manually

If you already know the host’s address, skip QR scanning:

1. On the client, open Add Device (desktop) or Add device (mobile).
2. Enter Host (for example 192.168.1.20), Port (defaults to 7431), and the 6-digit Code currently shown on the host. Optionally set a Name, such as Studio Mac.
3. Submit and wait for the host to approve the request.

What you get on the paired device

Once paired, the client shows a live view of the host, grouped by project. Each project lists its active branch or worktree and status:

• Green dot — session active
• Grey dot — idle / not running

Open a project to get a bottom navigation bar with:

• Agent — start, resume, or monitor Agent runs on the host
• SSH — open an SSH session hosted by the desktop
• Files — browse the project’s files (same as Explorer)
• Terminal — open a remote terminal into the host, including third-party CLIs such as OpenCode
• Browser — use Browser mode remotely

Manage connected devices

On the host, Settings → Remote Access → Connected devices lists every device with access:

• Each entry shows the device name, platform (Android, iOS, or Desktop), and last seen time.
• Revoke immediately disconnects a device and blocks future connections from it.
• Clear revoked removes revoked entries from the list.
• Pairing codes are single-use and expire after 2 minutes — click Regenerate on the host if a code expires before the client connects.

Security

• A device only appears as connected after the host explicitly approves the pairing — a client cannot force a connection.
• Disabling Enable remote access on the host closes the server immediately; already-connected devices lose access.
• Revoking a device is immediate and does not require the device to be online.