Remote projects

A remote project’s agents run on another machine, reached over SSH or in a WSL distribution. The canvas stays on your computer. The terminals, and the agents in them, run on the host. This page shows how to add a remote project and what happens when the connection drops.

Figure: The canvas is on your computer. The Cuewire server, the terminals and the project folder are on the host.

What you need

• A host that runs Linux on x86_64 or ARM64 (aarch64). A WSL distribution counts.
• For SSH: a host you can reach with ssh from your computer. Keys, an SSH agent or a password all work.
• The agents you want to run, installed on the host.

Add a remote project

1. In the sidebar, click + Remote project (SSH or WSL). A field opens.
2. Type where the project is, in one of these forms:
   • devbox:/srv/app or me@devbox:/srv/app: a folder on an SSH host. A name from your SSH config works.
   • wsl:Ubuntu:/home/me/app: a folder in a WSL distribution.
   • devbox, me@devbox or wsl:Ubuntu alone: Cuewire connects and lets you pick the folder.
3. Press Enter.

Figure: Add a remote project from the sidebar.

The project opens as a workspace named after the folder and the host, for example app on devbox. If Cuewire can’t read what you typed, the field stays open and lists the forms it accepts.

Pick the folder on the host

If you typed only a host, Cuewire connects and opens Choose a folder on devbox.

1. Click a folder to go into it. Click ../ at the top of the list to go back up.
2. When the folder you want is shown, click Open app (Enter). The button names the folder.

Figure: Choose a folder on the host.

The picker lists only folders inside your home folder on the host, or the folders the host’s owner allows. It never follows symbolic links, and shows at most 2000 folders. If the connection fails, it says why and offers Try again.

The first connection

Cuewire needs its server on the host. When it is missing, Cuewire installs it under ~/.cuewire/bin, over the same SSH or WSL connection. It uploads only server files that this build signed. Each file is checked on the host before it is used.

If SSH needs your password or a key passphrase, or sees the host’s key for the first time, Cuewire asks in a dialog:

• Sign in to devbox: type your password or passphrase. The field hides what you type, and nothing you type is stored. Sign in (Enter) sends it; Cancel (Esc) stops.
• Trust devbox?: shows the key’s fingerprint. Choose Yes, trust it (Enter) only if you recognise it. Otherwise choose No (Esc).

Warning

A host key you don’t recognise can mean you are talking to the wrong machine. Check the fingerprint with the host’s owner before you trust it.

Agents on the host

On an empty remote canvas, the Start here card offers the agents installed on the host. Agents that are not installed there are marked (not installed).

• Terminals start in the remote project folder.
• They use your login shell on the host, with its environment. So agents installed through tools such as nvm are found.
• Agents on the host follow the host’s own settings for those agents.

Some features work on your own computer only:

• Layers are not available on remote projects yet.
• Reviews, commits from the layer chip and pull requests run on this computer only.
• Sandbox profiles apply only to agents on your own computer.

Files on the host

File trees and file nodes show the project on the host: its folders, git changes, text and diffs. You can stage and unstage files there too. See Files and the editor.

• Edits are saved on the host.
• If an agent changed the file on the host since you opened it, your save is refused rather than overwriting its change. Reload takes the host’s version.
• Files and diffs larger than 512 KiB are not opened over the connection.

When the connection drops

Agents keep running on the host. Cuewire reconnects by itself. It waits a little longer after each failed try, up to 30 seconds.

While it is not connected, a banner says Reconnecting to devbox · attempt 3, with why the last try failed and when the next one is. Click Reconnect now to try at once. Terminals say Waiting for devbox….

Figure: The connection dropped. The agents keep running on the host while Cuewire reconnects.

When the connection is back, every terminal shows what happened while you were away.

The host keeps the last 4 MiB of each terminal’s output. Sometimes more was printed while you were away. Then, when you scroll back, a strip shows where the kept output begins: History lost · output before the last 4 MiB was not kept.

Two computers, one host

Cuewire keeps the canvas on the host too. So another computer can open the same project.

• If only one side changed the canvas, the change is taken over quietly.
• If both sides changed it, Cuewire asks This canvas changed here and on devbox. Choose Use the host’s copy (Enter), Keep mine, or press Esc to decide later.

One computer drives a host at a time. A second computer watches, read-only. It shows Read-only · another desktop is driving devbox and offers Take over. Taking over makes the other computer read-only.

Figure: Another computer drives this host. Take over to drive it from here.

Note

Your organisation can limit which hosts you may use. Cuewire then says why a host is refused. See For administrators.

What’s next

• Files and the editor: read and edit files on the host.
• Your phone as a companion: answer your agents while you are away.
• Privacy and security: how passwords and server files are handled.