Skip to content
throw99 edited this page Nov 17, 2026 · 13 revisions

A Host is a computer and account that runs Skiff sessions and data services. This computer is always the first Host. You can add servers that you reach over SSH. A window shows one Host at a time. The top bar shows the Host, and the window title reads "Skiff — ". Sessions, projects, Git, files, images, ledger, Skipper and agents come from that Host through the same capability-gated contract.

Settings › Hosts

Open Settings and select Hosts. The list has these columns:

Column Content
Name The Host's name. A check mark shows the Host in this window.
Server The SSH server.
Skiff The Skiff version on the server. Update… shows when an update is available.
Auto update A switch. When it is on, an older install that Skiff made updates as the app connects, if every session survives.
State Connected, Needs attention, or Not checked.
  • Click a row, or press Enter, to open its check list.
  • The row's ⋯, a right-click, the menu key or Shift+F10 opens the row menu: Check, Update Skiff… (when an update is available), Auto update, Edit…, Rename… and Remove….
  • Rename… changes the name only. The server stays the same.
  • Remove… removes the Host from this computer. Its sessions keep running on the server. If Skiff installed Skiff there, a switch can also uninstall it, and the dialog names the sessions that end. An install that Skiff did not make stays.

The Host menu in the top bar selects the Host for the window. The window then reloads. A Host that needs attention shows "Needs attention". Select it to open its check list. The menu also has Add SSH Host… and Manage Hosts…. When the shown Host is disconnected, the menu has Check …. For a server, the menu has an item that allows or blocks clipboard writes from it. Skiff blocks these writes until you allow them, and it asks first.

When the connection to a server stops, the top bar shows the Host as disconnected, and input is off. Skiff connects again by itself. It waits 1 second, then twice as long each time, up to 30 seconds. If the server answers as another Skiff install, Skiff stops. Check the server. Then select Accept new identity… in the top bar. Clipboard writes from that Host are then blocked again.

Add a server

  1. In Settings › Hosts, select Add SSH Host…. Or open the Host menu in the top bar and select Add SSH Host….
  2. The page lists the hosts in your SSH config, with where each one goes. Select Connect on a row. Skiff saves the Host and runs the check list.
  3. For a server that is not in your SSH config, select Other server…, and type its name or address. Name, User and Port are optional. A line under Server shows the user, the port and any jump host. Then select Connect.

The check list

The check list shows one row for each check, in order. A row after a failed row shows "Waits for the row above." A row that Skiff can fix has a button.

Check Fix buttons
Reach the server None. Check the name, or that the server is on.
Host key Trust this key… for a new key. Review… for a changed key.
Log in without a prompt Make key…, Unlock key…, Install key…, Show key file, Fix permissions…
Server supported None. Skiff runs on Linux and macOS, on x86_64 and ARM64.
Skiff on the server Install Skiff…, Update Skiff…. An install that Skiff did not make passes, and Skiff uses it as it is. A newer Skiff on the server shows a warning: update Skiff on this computer.
Sessions service (skiffd) Start, for an install that Skiff made
Socket forwarding None. The server's admin must allow AllowStreamLocalForwarding in sshd.
Skiff identity and version None. The row tells which side to update.
Projects service (skiff-host) Start. Without it, sessions work, and projects do not show.
Keeps running after logout Turn on…, Start

At the bottom are Check again, Switch to when the checks pass, and Done.

A changed host key shows the key that Skiff knows and the key that answers now. Skiff does not connect until you replace the key. Replace the key… asks again before it changes it.

Key setup

Button Result
Make key… Makes ~/.ssh/id_ed25519 with no passphrase on this computer, then opens Install key…. Skiff does not change a key that exists.
Install key… Asks once for your password on the server and adds your key to authorized_keys. Skiff does not store the password.
Unlock key… Asks for the passphrase and adds the key to the SSH agent. On macOS, the Keychain also keeps it.
Show key file Shows your public key file in the file manager, for the server's admin. Use it when the server takes known keys only. A key that only the SSH agent holds gets a file in this app's cache.
Fix permissions… Replaces the key file on the server with one that holds only this computer's key. Other keys then do not work, so Skiff asks first.

Install and update

Install Skiff… installs Skiff in your home folder on the server. It needs no admin rights.

  1. Skiff gets the server bundle of its own version and checks its signature.
  2. Skiff uploads it to ~/.local/share/skiff/server and links ~/.local/bin/skiff. If that name is taken, Skiff leaves it.
  3. Skiff starts skiffd and skiff-host.

The dialog shows each step. If a step fails, select Try again or Copy output.

Update Skiff… updates Skiff on the server to the version of this computer. The sessions keep running. If the running skiffd cannot hand its sessions over, a red dialog names the sessions that end and asks first. Skiff never moves a server to an older version. When the server runs a newer Skiff, update Skiff on this computer.

When no session runs, Skiff restarts skiffd with no dialog. If skiffd does not come back after an update, Skiff starts the old version again. Skiff keeps the previous version on the server for this. When the server has the same version from another build, the row shows Update Skiff… to install this app's build.

To install from a shell on the server, run curl -fsSL https://github.com/solutionscay/skiff/releases/latest/download/install.sh | sh. It needs no admin rights. Run it again to update. If an update must end sessions, the script names them and stops. Add --yes to continue. To remove Skiff, run ~/.local/share/skiff/server/current/install.sh --uninstall. Then add the server in Settings › Hosts.

Auto update in the Host list is on by default. On connect, Skiff then updates an older install that it made. An automatic update never ends sessions.

When the versions differ, the top bar shows a badge. For an older Skiff that Skiff installed, the badge is Update available, and its panel has Update Skiff…. For a newer Skiff on the Host, the panel tells you to update Skiff on this computer. When the Host speaks a different protocol, the window shows its sessions, and you can type in them. You cannot start or end sessions there. Update the older side. Skiff never changes a Skiff that it did not install.

Keeps running after logout

On Linux, Skiff runs skiffd and skiff-host as systemd user services. The install also tries to turn on lingering, so they keep running after you log out. If lingering is still off, select Turn on… in the check list. If the server does not allow lingering, the row tells you to ask its admin. On a server without a systemd user manager, Skiff starts them in the background. They then run until the server restarts.

macOS servers

A Mac server runs Skiff as two LaunchAgents. Skiff keeps running after you log out. After a restart, it starts when you log in on the Mac.

A Mac that has the Skiff app uses that app's Skiff. Skiff does not install a second one there. Open the app on the Mac, then check again.

Projects on a Host

To add a project, select Add project while the window shows the Host. A folder picker opens on the Host's Git repositories.

  • The left side has Home, Recent and Git repos.
  • The right side lists the folders, with Filter, Hidden and New folder…. The footer shows the full path.
  • The arrows move, Right opens a folder, and Left or Backspace goes up. Ctrl+Enter (⌘+Enter on macOS) selects the main button.

Select a folder, then Add project. A folder that is not in a Git repository becomes a plain folder project. It has no worktrees and no Changes, and it shows Files. On a Host with a Skiff older than 1.7.4, a folder that is not a Git repository shows Initialize repository… in place of Add project. For a folder that is a project already, the button is Show it.

On a Host, the project menu has no Show in file manager, no project icon or background, and no workspace items.

A file from a Host opens as a read-only copy on this computer. The copy opens as Settings › Open with says. The Files tree on a Host does not follow links. Skipper avatars are for this computer only. On a Host, Avatar… is off.

New sessions on a Host

New session on a Host opens a menu of folders on that Host: the focused session's folder, the worktrees, recent folders, Home folder and Choose a folder…. Each folder opens Shell and the Host's agents. Choose a folder… opens the folder picker with Start here.

Skipper and agents on a Host

Settings › Agents, Settings › Skippers and Settings › Task types show the settings of the Host in the window, under a band with its name. Changes go to that Host. A Host with an older Skiff shows them read-only.

  • Settings › Usage shows the plan limits of the Host's agents. Settings › Schedules shows the Host's schedules, which its skiffd runs. A Host with an older Skiff shows one line in place of each page.

  • Program in Settings › Agents shows where that Host found the program. Change… opens the folder picker on the Host, then a menu of the programs in that folder. A Host with an older Skiff has no such menu.

  • Admiral runs on the Host, in a folder on the Host. Change… opens the folder picker with Use this folder.

  • Edit on an instruction file copies the Host's file to hosts/<host>/skiff-agent/<same path> beside projects.toml on this computer, and opens the copy in an app as Settings › Open with › Text files says. When Text files opens in the peek, the copy opens in the default app: the peek runs on the Host. Each save of the copy goes back to the Host. When the file changed on the Host after Edit copied it, the Host refuses the save. The copy stays, and the row shows one line: "Changed on after you opened it. Your copy was not sent. Edit opens the file on again."

  • Reset… runs on the Host. A Host whose Skiff cannot send its files shows the Instructions rows with their status and no buttons.

  • When Admiral does not run on the Host, a click on its row shows "Admiral does not run on ." with Start Admiral. On a Host whose Skiff is too old, the line has Update Skiff….

  • Start project Skipper shows when the Host's Skiff can start one.

  • Start fleet Skipper shows when the Host's Skiff can start one. The fleet Skipper, its takeover of project Skippers, and Rename fleet… run on that Host: its projects.toml, its ledger and its skiffd. A Host with an older Skiff has no fleet Skippers. Its fleet menu has no fleet Skipper items.

See Skiff agent and Worktrees.

Clone this wiki locally