Skip to content

Other machines, over ssh ​

Use the daemon on another machine as you use this one: list its panes, run things in them, attach, or show the whole interface in your terminal. It all goes through your own ssh, and the daemon there opens nothing to the network.

You need two things:

  • ssh to that machine asks nothing. Use a key (loaded in your agent if it has a passphrase) and connect once by hand to accept the host's key. If ssh build true prints nothing and asks nothing, you're set.
  • isc is there, in the same version as here. isc host put brings it there. Or install it there yourself with the one-line install, which takes a version: see Installing. ~/.local/bin, /usr/local/bin and Homebrew's bin are looked in even when a shell started by ssh doesn't.

Name the machine once, then check it:

sh
isc host add build me@build.example.com
isc host check build

The second word is whatever you'd give ssh: a host, user@host, or a Host from your ~/.ssh/config. Your ssh configuration, keys, agent and jump hosts all apply.

isc host check NAME meets the machine, prints four lines, changes nothing and starts nothing. It fails unless the machine is ready to use. The other isc host commands are in every isc command.

A name may use ASCII letters and digits and . - _ + @ : % [ ], with ssh:// before it if you like (ssh://me@build:2222). Anything else is refused, in the settings file too. A Host in your ssh configuration with other characters isn't offered; give it a second name there.

isc host check prints four lines:

✓ Reached build · 42 ms
✓ insensical 0.3.0 is there
✓ Its server is running
✓ 3 projects, 1 wants you

They say whether ssh got there and how long a round trip takes, whether insensical is there in a version that works with this one, whether its server is running, and what's open there. ✓ holds and ✗ doesn't, with what to do about it underneath. Lines after a failure aren't tried and are marked ·. → marks what isc host put can put right. No server running yet isn't a failure: the first command that needs one starts it.

The names are lines under [hosts] in your settings file: build = "me@build.example.com". A machine can also carry an icon and a mark that it's one to be careful on:

toml
build = { ssh = "me@build.example.com", icon = "server", careful = true }
  • icon is one of server, laptop, desktop, mini, nas, board, container and cloud. Any other word shows as a server.
  • A tailnet machine that isc host add found also keeps its node: build = { ssh = "me@build", node = "nABC123CNTRL" }. See "A machine of your tailnet" below.

Putting insensical on a machine. If a machine has no isc, or an older one, isc host put build brings it to this version, never to a newer one: the two must match exactly. It says which way it went.

  • An isc there that can update itself is asked to. It runs isc upgrade --version with this version, downloading that release itself and checking its signature. That works on a Mac too. If the machine can't reach GitHub, a Linux machine gets a copy of isc from here instead, and you're told.
  • An isc that a package or Homebrew owns isn't touched. You get the command that updates it, to run there.
  • A machine with no isc, or one from before isc upgrade --check --json, gets a copy in ~/.local/bin, no sudo. That works on x86-64 and arm64 Linux. On a Mac you're given the line to run there yourself.
  • A server already running there is left running, on the older version, and you're told what a restart would come to. --restart-server does it, as does a yes to a second question at a terminal, or isc host restart build afterwards. A server that can move to the new version keeps everything in its panes. One that can't is stopped and started, which ends what runs in its panes, and you're told how many panes first.

Then put --host before any command:

sh
isc --host build ls
isc --host build run -- make test
isc --host build attach 3
isc --host build

The last one is the whole interface, in this terminal, on that machine's projects.

  • From inside the interface, "Go to a machine" in the palette lists this computer and every machine you've named, each tried while you look as reached (with its isc version) or not reached; mark one and the line below says why. Enter shows the marked machine's projects, and its name stands at the left of the top row. One machine is shown at a time, and what runs on the others runs on. A machine that can't be reached leaves you where you were, with a notice.
  • INSENSICAL_HOST=build in a shell does the same for every command you run there, except the ones that end something: isc kill-server, isc close, isc tab close, isc project close and isc project sleep. With only the variable set, those are refused and say which machine it names. Add --host build to act there.
  • What belongs to that machine is that machine's: its files in the file finder, a new project's directory (~ is your home there), a project's drawing. isc --host build integrate sets up the agents there, and isc --host build config set changes the daemon's settings there: see [Agents](/agents) and section 15.

When the machine can't be reached. A machine that has sent nothing for four seconds is given up on. A command says "the link to the other machine was lost" and ends. Nothing typed into the silence is delivered later: see Other machines in the window.

The interface dims your panes and puts a small card over them: "build is out of reach", how long ago it was last heard once that's over ten seconds, and the key to leave. It tries again after a second, then two, then four, up to every thirty seconds, and shows your panes again when the machine answers. Any key tries at once. Nothing there was touched.

If ssh would ask for a password or doesn't know the machine's key, the interface tries once and stops, since a machine that counts failed logins might lock you out. It says what ssh needs. Put that right, then press a key.

Typing on a far machine. When the round trip takes 70 milliseconds or more, a letter you type is drawn at once, a little fainter than the rest, and turns to its usual colour when the program shows it. Your keys still go to the program at once.

  • type-ahead = "off" turns it off. "on" draws ahead over any link to another machine, however quick. A pane on this machine never has it.

From a browser. isc hub on this computer can carry a paired browser on to these machines over the same ssh. Only a device you made with --far gets that; see "Your other machines, through this computer" under In a browser.

Tailscale, Headscale and WireGuard need nothing of their own. Give ssh the machine's name or address on that network:

sh
isc host add build me@build.tailnet-name.ts.net
isc host add nas me@100.64.0.7
isc host add office me@10.8.0.2

With Tailscale SSH there's no key to set up; ssh build true must still ask nothing.

A machine of your tailnet. A name on a tailnet stops working when the machine or the tailnet is renamed, or when this computer doesn't use the tailnet's DNS. The machine's address goes on. So when you isc host add one of your tailnet's machines, its node's id is written beside it, and it's dialled at its address:

sh
isc host add build me@build
  • --no-node keeps it as typed. So does a name your ssh configuration gives a machine. The window's Add Remote Host dialog keeps the node of a machine you choose under Tailscale or type by its tailnet name, and changing a machine's address in the settings sheet looks for its node as isc host set build --ssh me@build does.

When ssh has a question. A link is made by ssh told to ask nothing, so each thing it would have asked is a machine that isn't reached:

It saysWhat happenedWhat to do
ssh hasn't met build beforessh has no host key for it yetisc host answer build, and say yes once you've compared the fingerprint
build's host key is not the one ssh has for itThe key changed: a machine set up again, or another machine in its placeFind out why first. When you're sure, ssh-keygen -R build forgets the old key
ssh needs your key or password for buildIt wants a key, a passphrase or a passwordisc host answer build shows what it asks. A key in your agent (ssh-add) or on the machine (ssh-copy-id) lets it in
Tailscale wants you to sign in again before it lets ssh throughThe tailnet's rules ask for a fresh sign-inisc host answer build shows the link to sign in at
Tailscale's rules don't let you in as root on buildThe tailnet's access rules refuse that user, or youWhoever looks after the tailnet changes its rules
build is offTailscale says it isn't onlineTurn it on, or start Tailscale there
build did not answer in time, build could not be found, build refused the connection, build cannot be reached from this networkAs they sayThe line under each says what to check

isc host check prints ssh's own last line under these, after `ssh` said:.

isc host answer build runs your own ssh to the machine at your terminal, free to ask, running nothing there but true. You answer ssh's real question yourself; insensical doesn't read, keep or pass on what you type. Then it meets the machine and prints the four lines. It needs a terminal and succeeds only if the machine was then reached. For a machine you haven't named, give it where ssh goes: isc host answer me@build. In the window, the Answer button runs it for you in a new tab, and in the interface in a terminal a does in "Go to a machine".

What it doesn't do:

  • A link can't ask you anything. A host that wants a password, a passphrase or a yes to its key is refused, with what to do about it.
  • The two versions must match (isc version prints them). If they don't, you're told which machine has which. isc host put puts this version on the other machine. If the other machine's is newer, update this one.
  • --host is for isc and the interface in a terminal. The window shows every machine you've named at once: see Other machines in the window.
  • Some commands are about this machine only, and say so if you give them a host: daemon, proxy, restart-server and host. To restart the server elsewhere, use isc host restart build: it tells you what a restart comes to, and asks. If the server there already runs the installed insensical, it restarts nothing. Don't run ssh build isc restart-server: a shell started by ssh often can't find the server. isc --host build kill-server asks the daemon there to stop, and can't signal one that doesn't answer.
  • config reaches the daemon's settings there and no others. A setting of the interface, such as theme, is read from this machine's file, and isc --host build config set theme paper is refused. Leave --host out for those.
  • A path you click there is the other machine's. Only web addresses are followed on this computer. With nvim, vim, hx or nano in open-files-with, the click opens the file in a pane on that machine; otherwise it copies the path. See What a click on a path does.
  • INSENSICAL_SSH names a program to run in place of ssh, given the same arguments. INSENSICAL_TAILSCALE does the same for tailscale.