Remote Hosts
Open the shells of another machine in your Cogno window. Start a build in Cogno on your office PC, go home, and open the same shell on your laptop: the build is still running, and you see what it printed in the meantime. Cogno connects through ssh.
In this guide, the other machine is the one whose shells you want to reach (for example your office PC), and this machine is the one you sit at (for example your laptop at home).
What you need
Section titled “What you need”- On the other machine: Cogno, the desktop app you use every day, started in your desktop session. And an ssh server you can log in to (step 1).
- On this machine: Cogno. The ssh client it needs is part of Windows 10/11, macOS and Linux.
- Between them: this machine can reach the other one, in the same network or through a VPN.
- You log in as the same user that Cogno runs as on the other machine. With another account you see none of its shells.
The two Cognos do not need the same version. If they are too far apart, Cogno says which one to update.
Step 1: Set up the other machine
Section titled “Step 1: Set up the other machine”Do this once, on the machine whose shells you want to reach. Pick its operating system.
Windows
Section titled “Windows”Open PowerShell as administrator (right-click the Start button, Terminal (Admin)).
-
Install the ssh server, start it, and have it start with Windows:
Terminal window Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0Start-Service sshdSet-Service -Name sshd -StartupType Automatic -
Check that the firewall lets ssh in:
Terminal window Get-NetFirewallRule -Name *OpenSSH-Server* | Select-Object Name, EnabledIt must list a rule with
Enabledset toTrue. If it lists nothing, add the rule:Terminal window New-NetFirewallRule -Name sshd -DisplayName "OpenSSH Server (sshd)" -Enabled True -Direction Inbound -Protocol TCP -Action Allow -LocalPort 22 -
Note the name of the machine and its address:
Terminal window hostnameipconfigThe address is the line
IPv4 Address. Over a VPN, ask your IT which name or address reaches the machine. -
Keep the machine awake: Settings → System → Power (Power & battery on laptops), set When plugged in, put my device to sleep after to Never. Locking the screen is fine.
-
Open System Settings → General → Sharing and turn on Remote Login.
-
Click the ⓘ next to it. Under Allow access for, choose All users or make sure your user is in the list.
-
The line under Remote Login says how to reach the Mac, for example
ssh me@office-mac.local. Note the part afterssh. -
Keep the Mac awake:
- On a Mac with a battery: System Settings → Battery → Options, turn on Prevent automatic sleeping on power adapter when the display is off, and leave it plugged in.
- On a desktop Mac: System Settings → Energy, turn on Prevent automatic sleeping when the display is off.
Locking the screen is fine.
-
Install the ssh server and start it, with the commands for your distribution:
Distribution Commands Ubuntu, Debian, Mint sudo apt install openssh-serverandsudo systemctl enable --now sshFedora sudo dnf install openssh-serverandsudo systemctl enable --now sshdArch, Manjaro sudo pacman -S opensshandsudo systemctl enable --now sshdopenSUSE sudo zypper install openssh-serverandsudo systemctl enable --now sshd -
If a firewall is active, let ssh in:
Firewall Command ufw(Ubuntu)sudo ufw allow sshfirewalld(Fedora, openSUSE)sudo firewall-cmd --permanent --add-service=sshandsudo firewall-cmd --reload -
Note the name of the machine and its address:
Terminal window hostnamehostname -I -
Keep the machine awake: in the system settings under Power, turn off Automatic Suspend. Locking the screen is fine.
Step 2: Log in with a key
Section titled “Step 2: Log in with a key”Without a key, you type the password of the other machine each time you connect; Cogno asks for it in a dialog. With a key, you skip the password. You create the key on this machine and allow it on the other machine.
Create the key on this machine
Section titled “Create the key on this machine”Open a terminal (on Windows: PowerShell, no administrator needed) and run:
ssh-keygen -t ed25519Press Enter at every question. If it says that the file already exists, you have a key
already: answer n and use that one.
Then show the public key, a single line that starts with ssh-ed25519:
| This machine | Command |
|---|---|
| macOS, Linux | cat ~/.ssh/id_ed25519.pub |
| Windows | Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub |
You can send this line by mail or chat. The file of the same name without .pub is your
private key: keep it on this machine and do not share it.
Allow the key on the other machine
Section titled “Allow the key on the other machine”The other machine runs macOS or Linux, and this machine too: one command on this machine does it all. It asks for the password of the other machine once:
ssh-copy-id me@office-mac.localThe other machine runs macOS or Linux, this machine runs Windows: open a terminal on the other machine and run these lines, with your key line between the quotes:
mkdir -p ~/.ssh && chmod 700 ~/.sshecho "ssh-ed25519 AAAA... me@laptop" >> ~/.ssh/authorized_keyschmod 600 ~/.ssh/authorized_keysThe other machine runs Windows: where the key goes depends on whether your account there is an administrator.
-
Administrator (the usual case on your own PC). Windows reads the keys of all administrators from one shared file. Open PowerShell as administrator on the other machine and run, with your key line between the quotes:
Terminal window Add-Content C:\ProgramData\ssh\administrators_authorized_keys "ssh-ed25519 AAAA... me@laptop"icacls C:\ProgramData\ssh\administrators_authorized_keys /inheritance:r /grant "*S-1-5-32-544:F" /grant "*S-1-5-18:F"Do not skip the second line: the ssh server ignores the file if anyone but administrators and the system can read it.
-
Standard account. Open PowerShell (no administrator) on the other machine and run:
Terminal window New-Item -ItemType Directory -Force $env:USERPROFILE\.sshAdd-Content $env:USERPROFILE\.ssh\authorized_keys "ssh-ed25519 AAAA... me@laptop"
Try it
Section titled “Try it”On this machine, connect once by hand, with the name or address from step 1:
ssh me@office-pc- The first time, ssh asks whether you trust the machine. Answer
yes. - You should get a prompt of the other machine without being asked for a password. Type
exitto leave.
Then check that ssh can start Cogno there. This works once Cogno has been started on the other machine at least once.
| The other machine | Command on this machine |
|---|---|
| Windows | ssh me@office-pc '.cogno\bin\cogno --version' |
| macOS, Linux | ssh me@office-mac '.cogno/bin/cogno --version' |
It must print the version of Cogno, for example cogno 0.5.0, and nothing else. The
commands work the same in every terminal of this machine: PowerShell, bash or zsh.
If either check fails, Cogno cannot connect either. Fix it here first, where you see what ssh says; see When something goes wrong.
Step 3: Add the other machine in Cogno
Section titled “Step 3: Add the other machine in Cogno”On this machine, open the Remote panel in the side menu and click +.
| Field | What to enter |
|---|---|
| Name | Any name for the machine, for example office. Letters, digits, - and _. |
| Destination | What you typed after ssh in step 2, for example me@office-pc. |
Click Save. Cogno finds out by itself how to start Cogno on the other machine. If the ssh server there uses PowerShell, ssh may ask for the password twice, but only the first time you connect. To set the command yourself, open Advanced.
Step 4: Open the shells of the other machine
Section titled “Step 4: Open the shells of the other machine”- On the other machine, Cogno is open, with the shells you want to use.
- On this machine, click Connect next to the machine in the Remote panel. The dot in front of its name turns yellow while it connects and green when it is connected.
- Below it you see the shells of the other machine, grouped by workspace and tab, as they are arranged there.
- Click a shell. It opens here in a tab of its own, with what it printed last.
On the other machine, Cogno now shows that this shell is open elsewhere. Click Show it here there to take it back.
Keep the shells running when Cogno closes
Section titled “Keep the shells running when Cogno closes”By default, the shells of a machine end when you close Cogno there. To keep them running, set this on the other machine:
terminal.keep_shells_running = trueAdd it to the config. It applies to shells started after the change.
- You can then close Cogno on the other machine and still reach its shells from this one.
- When you start Cogno there again, its tabs show the same shells, with what they printed in the meantime.
- Closing a tab still ends its shell.
- Logging out or restarting the other machine ends its shells.
Using it day to day
Section titled “Using it day to day”- A shell is open in one Cogno at a time. When you click it in the Remote panel, it moves to this Cogno; the Cogno that showed it before says where it is open now.
- A shell goes back to the Cogno on the other machine when you close its tab here, click Disconnect, or close Cogno.
- Closing the laptop leaves the shells of the other machine running. It can take a few minutes until Cogno there shows them again.
- Closing a tab here does not end the shell. It keeps running on the other machine. To end it, click the bin icon next to it in the Remote panel. The icon appears when the shell is open nowhere.
- Tabs come back. The tabs you opened this way are saved with your workspace. When you start Cogno again, they connect by themselves.
- A shell without a tab gets one. If a shell still runs but no tab shows it (for example after a crash), Cogno opens a tab for it in the Default Workspace when it starts, and tells you in a notification.
The list of shells updates when you connect and when you click the refresh icon. The pencil next to a machine changes it, the bin removes it.
What you see in a shell of the other machine
Section titled “What you see in a shell of the other machine”You see what the shell printed last (about the last megabyte), not a picture of the old window.
- A full-screen program such as vim or less redraws itself for the new window size.
- A program that draws over several lines without using the full screen may look untidy until it draws again.
- The tabs and splits of the other machine do not come along: each shell gets a tab of its own.
What works in a remote tab
Section titled “What works in a remote tab”| Works | Not yet |
|---|---|
The terminal itself, prompt markers, the working directory, command history (kept apart per machine), autocomplete from history, the process panel, coding-agent status, cogno action run typed in that shell | The Git panel, path completion from the file system |
When something goes wrong
Section titled “When something goes wrong”| Message | What to do |
|---|---|
Permission denied (publickey,...) | The other machine does not accept your key. Repeat Allow the key on the other machine. On Windows, check that you ran the icacls line. |
UNPROTECTED PRIVATE KEY FILE! (this machine is Windows) | Your private key can be read by others. Run icacls $env:USERPROFILE\.ssh\id_ed25519 /inheritance:r /grant:r "$(whoami):F" /grant:r "*S-1-5-18:F" /grant:r "*S-1-5-32-544:F" in PowerShell. |
Connection timed out or Connection refused | This machine does not reach the other one. Check the VPN, the name or address, the firewall (step 1), and that the ssh server runs there. |
Could not resolve hostname | The name is unknown in this network. Use the address from step 1 instead. |
Cogno does not run on that machine: open it there | Cogno is not open on the other machine. Open it there. |
No Cogno host answered | Cogno has never run on the other machine under the user you log in as. Start it there once. |
The Cogno on ... is older than this Cogno can talk to: update it there | Update Cogno on the other machine. |
The Cogno host is newer than this Cogno can talk to: update this Cogno | Update Cogno on this machine. |
The Cogno host of this machine is from an older Cogno, which this one cannot talk to | You updated Cogno while shells from the older version still run. Click End old host in the tab: the shells of the older version end, and new ones start. |
Host '...' is not defined in remote.hosts | A saved tab belongs to a machine you removed from the Remote panel. Close the tab. |
A tab says The shell no longer runs on ... | The shell has ended since. Close the tab. |
To see what ssh itself says, run the checks from Try it again.