Connect over SSH
Use Octoboard on a Linux server or another computer from this computer, in the desktop app or a browser, through SSH: an encrypted connection straight to that machine, with no relay or cloud service.
Not sure this is the way for you? Choose how to connect compares it with the browser-only ways that don’t need SSH.
Desktop app on this computer · Browser via an SSH forward ⟷ SSH ⟷ Linux server or another computer
New to this?
- Host: the machine Octoboard runs on and that you want to reach, a Linux server or another Mac or Windows PC.
- Server: here, a Linux machine you sign in to over the network, usually one you rent, with no screen of its own.
- SSH: a standard, encrypted way to sign in to another machine and type commands on it. It’s built into macOS, Windows and Linux.
- Terminal: the window you type commands into: Terminal on macOS, PowerShell on Windows.
- SSH forward: an SSH command that makes something on the host appear on your own computer, so your browser can open it there.
- Fingerprint (host key): a short code that identifies a machine’s SSH. Checking it once tells you that you reached the right machine.
- Key file: a file that signs you in instead of a password. Some server providers give you one.
What you need
Section titled “What you need”-
A way to sign in to the host with SSH. For a Linux server, its provider gives you the address and your user name. To check that it works, open Terminal (macOS) or PowerShell (Windows) and run the command below with your user name and the server’s address. The first time, answer
yeswhen it asks whether to trust the server.Terminal window ssh <you>@<server>For a Mac or Windows PC as the host, you turn on SSH sign-in in its system settings; Use another computer as the host shows how.
-
For a Linux server, Octoboard installed and started on it. Installation › Linux server shows how. Octoboard’s server program, octoboardd, is what the app calls the daemon.
-
The Octoboard app on this computer, for macOS or Windows, unless you’ll use only a browser.
Connect to a Linux server
Section titled “Connect to a Linux server”-
Sign in to the server over SSH as the user who runs Octoboard, run this command and copy the line beginning with
octoboard+ssh://: the connection details, which tell the app where and how to connect.Terminal window octoboardd connectionIf this computer reaches the server at a different address or SSH port, add
--hostor--ssh-portto the command to print the right connection details.The QR code it also prints holds the same line. No app scans it yet.
-
In the Octoboard app on this computer, open Remote devices from the rail on the left or, on macOS, choose Remote › Remote Devices from the menu bar. On Windows, you can also choose Remote devices from the window’s system menu or from the taskbar icon’s jump list.
-
Select Add remote daemon, then Paste under Connection details to fill in the fields.
-
Under Authentication, choose Password if you sign in with your account password. Choose Key file if your server provider gave you a key file instead (often named like
id_ed25519or ending in.pem), and enter where it is on this computer. -
Select Save, then Connect. Enter your password if it asks.
If you pasted the connection details, the server’s identity (its fingerprint) came with them, and the app checks it for you. If you typed the address by hand, the app shows a fingerprint the first time. To be sure you reached the right machine, compare it with the one this command prints on the server, and connect only if they match:
Terminal window ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
You’ll know it worked when a separate Octoboard window opens, showing the server’s projects and sessions.
Use another computer as the host
Section titled “Use another computer as the host”You can also reach a Mac or Windows PC that runs the Octoboard app.
- On the computer you want to reach, open Settings › Remote access in Octoboard.
- Select Open System Settings (macOS) or Open Settings (Windows) there, and turn on Remote Login (macOS) or OpenSSH Server (Windows), following the path the row gives, so this computer accepts SSH sign-ins. This needs an administrator. Back in Octoboard, the row then shows On.
- Turn on Allow remote access, select Allow to confirm, and keep Octoboard running: if you quit it, remote access stops.
- On the Octoboard app tab, select Copy connection details, and send them to the other computer, for example by email or chat.
- On the computer you’ll work from, add the host as in steps 2 to 5 of Connect to a Linux server, pasting the details you sent. Sign in with your user name and password on the host.
You’ll know it worked when a separate window opens with the host’s projects and sessions.
From a browser
Section titled “From a browser”-
Get the SSH forward command:
-
On a Mac or Windows host, first do steps 1 to 3 of Use another computer as the host. Then, on the Browser tab, look at Step 1: SSH forward. Click the address in the command to choose how your other computer reaches this one (or choose Enter the address yourself and replace
<server>later), then select Copy forward command. Also select Copy address under Step 2: Browser address. -
On a Linux server, run this on the server. It prints the browser address, then the SSH command to run.
Terminal window octoboardd addressReplace
<server>in the command with the server’s address.
-
-
On the computer you’ll browse from, run the SSH command in Terminal (macOS) or PowerShell (Windows). The window may ask for your password, then shows nothing more; that’s normal. Leave it open while you work: closing it disconnects the browser.
-
Open the browser address, which starts with
http://127.0.0.1:, in your browser.
You’ll know it worked when Octoboard opens in the browser tab without asking you to sign in.
Only someone who can reach Octoboard through the SSH forward can use this address. Keep it private: its key gives full control, and it stays in the browser’s history and bookmarks, and syncs to your other devices if browser sync is on.
If it doesn’t work
Section titled “If it doesn’t work”- “Could not reach the server”, or the SSH command says “Connection refused” or times out: SSH sign-in is off on the host, or the address or SSH port is wrong. Check that Remote Login or OpenSSH Server is on, and that you can sign in with the
sshcommand above. - “Could not sign in”, or “Permission denied”: the user name, password or key file is wrong.
- “The host key does not match”: the machine answering isn’t the one you connected to before. This happens after a server is reinstalled, but it can also mean something is wrong. Don’t continue until you know why.
- The browser page doesn’t load: the SSH window was closed, or its command stopped. Run it again and reload the page.
Security
Section titled “Security”- No extra public ports: Octoboard only accepts connections from the host itself, so to connect from another computer you first need to sign in to the host over SSH. This is why you need SSH, or one of the relays.
- Check which machine you reach: the app remembers the host key, the machine’s SSH identity, on the first successful connection and blocks the connection with an alert if that identity later changes.
- No password stored: after you first sign in with a password or your own key file, the app sets up a separate SSH key for this computer to use for future sign-ins.
- Take away a computer’s access: remove that computer’s entry from the host’s list of allowed SSH keys (
~/.ssh/authorized_keyson Linux and macOS). That key then can’t sign in again; a connection already open stays until it ends.
In a remote window
Section titled “In a remote window”- One window per SSH destination: connections with a different user name, host or SSH port each open their own window, so their projects, sessions and notifications never mix.
- See each connection’s status: open the app’s menu bar icon on macOS or its notification-area icon on Windows to see a tab for each connection.
- Open remote websites here: when an agent starts a website on the host, click the
localhostlink it gives, and the app opens that website on this computer through SSH. - Open remote files here: view a file in the remote window or download a copy to open in this computer’s default app for that file.
- Reconnect automatically: if the network drops, the window keeps trying to reconnect until it gets through or you close it.