Skip to content
GitHub Download

Connect a server

Add a Linux server to HeadlessOS with a password, SSH key or SSH agent. See what a server needs, and how to reconnect or remove one.

You add a server once, then sign in to it from the Sessions tab of the Control Center.

Check that you can log in from a terminal on the same computer:

Terminal window
ssh pi@192.168.1.20

Note the address, port and username that worked. HeadlessOS doesn’t read ~/.ssh/config, so enter the real values, not a host alias.

Any Linux server with SSH can connect. Some apps use more:

AppNeeds on the server
TerminalNothing extra
Dashboard, Task ManagerStandard Linux tools such as df, free, ip and ps
File ExplorerSFTP, which is on by default on most servers
Dockerdocker, run as root or a member of the docker group. If it’s missing, the app offers Install Docker
Servicessystemctl. Without systemd, it reads service --status-all instead
Server AdminStandard Linux tools. Packages needs apt, Firewall needs ufw, Web server needs nginx

Many actions, such as stopping a service or adding a firewall rule, run through sudo, and HeadlessOS can’t type a sudo password for you. For those, sign in as root or use passwordless sudo. In the Terminal app, sudo works as usual.

  1. On the Sessions tab, click Add Server. From the desktop, press Ctrl+Shift+Space (Cmd+Shift+Space on a Mac) to get back there.

  2. Fill in the form:

    FieldWhat to enter
    Display NameAny name, such as Home Pi
    HostAn IP address or hostname, such as 192.168.1.20 or example.com
    PortThe SSH port. It starts at 22
    UsernameThe login user. It starts at root
    AuthenticationPassword, SSH Key or Agent, as described below
  3. Click Add Server.

The server appears as a tile. Adding it doesn’t connect or test anything.

Choose Password and type it. HeadlessOS encrypts the password and saves it on this computer, so it can reconnect for you.

You can also leave the field empty and type the password each time you sign in. It’s then not saved, and HeadlessOS can’t reconnect on its own.

Choose SSH Key, then a Key Source:

  • Auto-Detect looks in ~/.ssh on this computer for private keys named id_*. It selects the first one. Use Detected Keys (~/.ssh) to pick another.
  • Upload File lets you choose a private key file from anywhere.
  • Paste Key takes the text of the key, including the -----BEGIN line.

If the key has a passphrase, type it in Passphrase (optional), or leave that empty and type it at each sign-in.

The server must already have the matching public key. To add it from your computer:

Terminal window
ssh-copy-id pi@192.168.1.20

Choose Agent and enter nothing else. The form shows “Will use your local SSH agent (SSH_AUTH_SOCK)”.

The agent must be running with your key loaded, and SSH_AUTH_SOCK must be set where the app starts. It usually isn’t on Windows, so use Password or SSH Key there. On macOS or Linux, try starting the app from a terminal where ssh-add -l lists your key.

Click the server’s tile. Type the password or key passphrase if you didn’t save it, then press Enter or click the arrow. With Agent, click Sign in.

A wrong password fails straight away. A network problem can take close to a minute, because HeadlessOS tries up to four times. Either way, the screen shows the reason. See Troubleshooting.

On a Mac, a server on your local network also needs local network access.

When an app needs data and the connection has gone, HeadlessOS reconnects with your saved credentials. If that can’t work, the app shows Server disconnected. Click Reconnect, or Back to login to sign in again.

There is no edit form. To change a server’s details, remove it and add it again.

On the Sessions tab, hover over the tile and click the red button, or right-click the tile and choose Remove server…. Then click Remove. Nothing changes on the server itself.