Repository navigation
Remote Hosts
Open sessions on other machines in your own client, run panes on another machine, and script across hosts.
TUIOS can reach other machines over ssh. Once a machine is added as a host, you can list its sessions and agents, open one of its sessions in your own client, run a single pane on it inside a local session, and send commands and messages to it.
Each host needs TUIOS installed. Your daemon holds one ssh link to each host and talks to the TUIOS daemon on the other side. There is no new listening port and no second login system: ssh decides who can connect.
Tip
This part is interactive on the docs site. Open it on tuios.dev.
(Unreleased)
tuios hosts setup takes a machine from nothing to linked. It reads the machine over ssh with BatchMode on, and changes nothing there until you agree.
# See what the setup would do, and change nothing
tuios hosts setup gaurav@buildbox --dry-run
# Copy this tuios there, start it at boot, add it both ways
tuios hosts setup gaurav@buildbox --name build \
--install copy --service --both-ways --yesA failure gets its one fix, such as ssh-copy-id. A fix that needs you, such as a password or a host key to check, stops the setup with the command to run.
--install picks how: copy (a copy of this tuios), release (the release of this version), pkg (the package manager there, with --pkg yay|paru|brew|nix|go), script (the install script) or none.
--service also starts it at boot. See Start the daemon at login.
--name names it here. A link that does not come up is removed again, unless you pass --keep.
With --both-ways, the other machine tests its way back first. Nothing is added there when it cannot connect. --as and --address say how that machine names and reaches this one.
On a terminal, tuios asks for each choice the flags do not make, and Ctrl+C stops the setup at the end of the step. Without a terminal every choice comes from a flag: a missing choice stops the command before it changes anything (exit 2), and a fix that needs you stops it with the command to run (exit 3). --json prints the steps and the result for a script.
Warning
No passwords, no changed keys
tuios never takes a password, and it never accepts a changed host key.
--tailnet lists the machines on your tailnet with their state. On a terminal it is a checklist: Space ticks a machine, a ticks every machine that can be set up, and Enter sets them up with one set of answers. o gives one machine its own answers. Each machine then gets a line with its step and a bar. --all, or --only with names, skips the checklist. At most 4 machines are set up at once, and one failure does not stop the others.
"Add a machine" in the palette, or the row of that name on the Hosts page of Settings, opens the same setup as a sheet in five steps: Pick, Test, Set up tuios, Both ways and Done. Pick has three tabs: an address, the machines on the tailnet, and the names in your ssh config. A step that needs you opens a pane that shows the command and runs it on Enter, and the sheet tests again when that pane ends. Esc stops it, and the config file stays as it was before the add step.
When a pane logs in with ssh or mosh to a machine that no [hosts] entry reaches, the dock offers it: "buildbox is not a machine here. Add it?", with Add, Not now and Never. Add opens a pane that runs tuios hosts setup for that machine. Never is kept, and the Alerts tab of Settings lists it with a row that removes it. A tunnel, a remote command without -t, and the ssh that scp, rsync, git, sftp or sshfs start do not count.
tuios hosts add build gaurav@buildboxThe name (build) is what you type later. It takes letters, digits, dot, dash and underscore. The address is anything ssh understands, including an alias from ~/.ssh/config.
The command writes the [hosts] table in your config file. The link is tested at once and the result is printed. A host that does not answer is still added.
From a terminal outside TUIOS, the running daemon opens the new host with no restart. From a pane, the new host waits for tuios config apply from a terminal outside TUIOS. A host that you add with "Add a host" on the settings page applies at once. See Changes that wait.
tuios hosts # every host and the state of its link
tuios hosts test build # dial it now and print what ssh said
tuios hosts test build --start # start its daemon if it does not run
tuios hosts remove build # drop ithosts add also takes:
-
--ssh-option ARG: one extra ssh argument. Repeat it, for example--ssh-option -J --ssh-option bastionfor a jump host. -
--connect-timeout SECONDS: how long one dial may take (default 10). -
--command PATH: the TUIOS binary to run on the host. Without it, the link looks on thePATH, then in the usual install locations, then in a login shell. -
--repos-root DIR: where the host keeps its checkouts, such as~/src.fan --host,worktree new --hostandstart-agent -s HOST:SESSIONlook there for a repository by its origin URL.
Warning
Accept the host key first
The daemon runs ssh with BatchMode on, so a link never asks for a password or about a host key. Run ssh to the host once by hand to accept its key, and use key-based login.
A link can use an ssh master that is already open. A client that can ask you for a password or a code, such as tuios-gpui, keeps that connection open in $XDG_RUNTIME_DIR/tuios/cm, or /tmp/tuios-<uid>/cm when XDG_RUNTIME_DIR is not set. Each link and tuios hosts test then use the master when one is open for that machine. A machine that needs a password or a second factor works for as long as the master is open. With no master open, ssh connects as before. TUIOS stores no secret.
A link does not use the folder in these cases:
- Other users can open the folder or its parent, or either is a symbolic link.
- Your
~/.ssh/configgives the host its ownControlPath. The link uses the master you open there. - The host forwards the agent (
ForwardAgent). A connection through a master gets the forwarding of the master, so the link would lose its agent. - A socket path in the folder is too long. The limit is 107 characters on Linux and 103 on macOS.
- TUIOS runs on Windows. Win32-OpenSSH has no
ControlMaster.
| Status | Meaning |
|---|---|
up |
The link is open and the remote daemon answers |
no_daemon |
The machine is up and no TUIOS daemon runs on it. See Start the daemon on a host |
no_tuios |
The machine is up and the link cannot find TUIOS on it. tuios hosts test shows where it looked |
unreachable |
The last attempt failed. The line under the table says why |
reconnecting |
The link dropped and TUIOS is dialling again |
tailscale_check |
Tailscale SSH waits for you to approve the login. The line under the table gives the link to open. See Tailscale SSH check mode |
incompatible |
The two sides speak different control protocol versions. Update one of them, or run tuios hosts sync
|
connecting |
The first attempt has not finished |
tuios hosts add writes this for you. You can also edit it by hand:
[hosts.build]
addr = "gaurav@buildbox"
[hosts.lab]
addr = "lab-01"
connect_timeout = 5
command = "/opt/tools/tuios"
ssh_options = ["-J", "bastion"]ssh_options accepts only safe options, such as -J, -p and -o Keyword=value. TUIOS drops a host with a refused option, such as ProxyCommand or a port forward, and tuios hosts names the reason. Put such options in ~/.ssh/config. See Rules for ssh_options.
A machine behind NAT is a reachability problem for ssh. Any tool that works as an ssh ProxyCommand in ~/.ssh/config works here too. See Configuration for an example.
If this machine is on a Tailscale tailnet, TUIOS can list the machines on it:
tuios hosts tailnet arch-btw arch-btw.example.ts.net offline
+ ente ente.example.ts.net
= forgejo forgejo.example.ts.net already the host forgejo
my-phone my-phone.example.ts.net cannot run tuios (iOS)
Add one by its name:
tuios hosts add ente --tailnetNothing is added on its own. The list only saves you typing the MagicDNS name. A host added this way is still reached over ssh. TUIOS gets the list by running tailscale status --json, looked up on PATH and then inside the macOS app bundle, so it needs no root and no auth key. Without the tailscale command, the list is empty.
By default the list leaves out machines that are offline, this machine, machines shared from another tailnet, and phones and tablets. The [tailscale] table changes that:
[tailscale]
addr = "dns" # dns (MagicDNS name), name (short name) or ip (100.x address)
user = "ubuntu" # ssh login put in front of every address
os = ["linux", "macOS"] # an empty list offers every OS
offline = false
include = ["*"]
exclude = ["*-pad-*"]
[tailscale.users]
build = "root" # per-machine login, wins over usertuios hosts tailnet --json gives every machine with offered, and a skipped reason when it is false.
Tailscale SSH can hold a login until you approve it in a browser. This is "check" mode. ssh then waits, and Tailscale prints a link to open:
# Tailscale SSH requires an additional check.
# To authenticate, visit: https://login.tailscale.com/a/l1d9c7e392d3020
TUIOS reads this link and shows it.
-
The daemon's link shows
tailscale_checkintuios hosts, with the link to open. The link waits up to 10 minutes. It goes on when you approve the login. -
tuios hosts testandtuios hosts addreporttailscale_checkwith the link. Open it, approve the login, then run the command again. -
tuios hosts syncon a terminal lists the link of each host that waits. Then it asks to wait up to 5 minutes. Each host continues when you approve its login. Without a terminal, or with--json, the host fails at once. Its row has"error_kind": "tailscale_check"andapproval_url.
All ssh calls of one hosts sync run to a host use one shared connection. Thus one approval covers the whole run. The connection uses a private socket in $XDG_RUNTIME_DIR and stops when the run ends.
If the tailnet policy refuses the login, TUIOS names the user it refused. The row has "error_kind": "tailscale_policy". Change the user in the addr of the host in [hosts], for example addr = "ubuntu@ente".
(Added in v0.10.0)
After a laptop wakes from sleep, the connection under a link can be dead with no sign of it. TUIOS finds such a link and dials again:
- A link that carried nothing for 15 seconds sends a check to its host and waits 5 seconds. Two missed answers end the link, and TUIOS dials again.
- A link that carries traffic sends no check.
- After this machine wakes, one missed answer ends the link. A link that waits to dial again dials at once.
- The
retry-hostverb, such astuios call retry-host '{"host":"build"}', checks a link that is up at once, and ends it after one missed answer. On a link that is down, it starts the dial again from a wait of 1 second. A click on a session of that host in the rail does the same.
An ssh master connection (ControlMaster) can outlive the network under it. The first dial after a dead link runs ssh with -o ControlPath=none, so it opens a connection of its own. A host that needs a password or a second factor fails that one dial. The dial after it uses the master again.
tuios attach --host build api # attach the session api on build
tuios new --host build # create a session on build and attach it
tuios new --host build ci --detach # create the session ci on build and return
tuios ls --all-hosts # sessions on every machineThe session is drawn in your client, with your theme, config and prefix key. Nothing is nested. The connection goes through your local daemon and its link to the host.
In the rail, sessions are grouped by machine. Press Enter on a session under a host to attach it, or on the + beside a host to create a session there. While you are on a host, the rail lists this machine's sessions under local. Press Enter on one to come back.
If the link drops, the session keeps running on the host. Your client keeps the pane on screen, the dock says it is reconnecting, and TUIOS dials again on its own. After three minutes it gives up, says why, and returns you to the session you left on this machine.
--ssh runs ssh to the host and starts the TUIOS there instead. Use it when the host's TUIOS is too old to serve your client. You then see the remote client nested in yours, and you press the prefix key twice to send it to the inner one.
A single pane can run on another machine while it stays in a local session:
tuios new-window deploy --host buildThe palette has the same thing as New window on another machine. The pane is drawn, laid out and closed here. Only its process runs on build. Its title bar reads build:deploy, so two panes side by side never look alike when they are on different machines.
The session is still an ordinary session: tuios ls, scripting, the mailbox, hooks and resurrection work on it as usual. The host runs only the process and its pty. It keeps no screen or scrollback for the pane, and the pane does not appear in tuios ls on the host.
Agent detection works in such a pane: the local daemon asks the host what the pane is running. An agent inside it can also report its own state and read its own mail with the usual commands and hooks: the report goes to the daemon on the host, which passes it back over the link as that window and nothing else. These panes have TUIOS_PANE_ID, TUIOS_PANE_HOSTED=1, TUIOS_HOST set to the host, and TUIOS_SESSION_REMOTE set to the session name here. They do not have TUIOS_SOCKET or TUIOS_SESSION, since those would name a daemon and a session on the host.
To paste an image from your clipboard into such a pane, press Ctrl+B V. TUIOS sends the image over the link. The host saves it to a file, and TUIOS pastes the path of that file into the pane.
The same works in a session attached with tuios attach --host. It also works (Added in v0.9.3) in a pane of this machine that runs ssh to a machine in your [hosts] table. TUIOS finds the entry that matches the ssh command, and writes the image on that machine. The host must allow files from this machine. When TUIOS cannot tell which machine the pane is on, it pastes nothing and shows a message that says why. See Paste an image.
Limits:
- The pane outlives a dropped link for a while. The host keeps its process running for its
hosted_grace(10 minutes unless the host's config says otherwise) and keeps its last 64 KB of output. The title bar reads[reconnecting] build:deploy, and keys are refused rather than queued. When the link comes back, the pane is reattached and what it printed meanwhile is written to it. If the grace runs out first, the pane closes. - Closing the pane ends its process at once.
- Each pane on the link has its own window of data in flight. A pane that you do not read makes its program wait, and the other panes on the machine keep running. When one machine runs an older TUIOS, a pane that you do not read can stop the link for up to 30 seconds.
- A restart of this daemon does not reattach. The processes on the host wait out their grace and end.
- A resurrected session brings the pane back as a local shell.
- Both machines need a TUIOS new enough to open remote panes. An older one refuses with a message that says to update.
(Added in v0.11.0)
A program in such a pane can show a kitty image that it names by path. kitten icat --transfer-mode=file and kitten icat --transfer-mode=memory work there:
kitten icat --transfer-mode=file diagram.pngThe path names a file on the host, so the host reads the file and sends the bytes over the link. The image then shows here, after the output that came before it. Other panes on the link do not wait for it.
The host reads only the files that the link may read:
- The host must allow
filesfrom this machine. Without it, the host refuses the image, as an older TUIOS did. - The read deny list applies. Keys, credentials, shell start files, histories, browser and chat folders, and TUIOS's own state are never read.
-
files_read_rootson the host limits the folders it reads. - A file with more than one name (a hard link) is refused.
See Files over a link for the rules. A program that sends the image bytes in its output, such as kitten icat --transfer-mode=stream, works with every host. Both machines need TUIOS v0.11.0 or newer for images by path.
A session with panes from several machines belongs to none of them. Once a second machine is reachable, the rail draws a global group above the machines for such sessions.
tuios new deploy --globalA global session starts with no panes. Every way of making a pane in it (the key, the rail's +, the palette) asks which machine to run on. Turn the group off with appearance.global_session = false.
Name the host in the target and a command runs on that host's daemon, through the link:
| Target | Means |
|---|---|
-s HOST:SESSION |
A session on a host |
-w HOST:SESSION:WINDOW |
A pane in a session on a host |
-s local:NAME |
A session on this machine whose name contains a colon |
tuios list-windows -s build:api
tuios capture-pane -w build:api:0
tuios send-text -s build:api -w 0 'make test'
tuios wait-for window-idle -w build:api:0
tuios list-agents --host build
tuios kill-session build:apiA task card of a repository that another machine owns works the same way. The pane that holds it attaches files with tuios task attach -s HOST:SESSION, and a screenshot or a capture is taken there and passed on over the link, at most 3 MiB. See Attachments.
The CLI says which host answered, and --json adds a host field. A host name is matched exactly. An unknown name fails with unknown_host and lists the configured names, and a host that is down fails with host_unreachable. A command is not queued for later.
(Unreleased)
tuios run --host runs one shell line on a linked machine, with no pane, and exits with its status:
tuios run --host build -- uname -a
tuios run --host build --timeout 60000 -- fc-list : family
tuios run --host build --cwd ~/src/api -- git status --shortThe host's daemon runs the line under sh -c, with no input. tuios prints what it wrote to stdout and stderr on its own stdout and stderr.
-
--cwdsets the folder there. The default is its home. -
--timeoutstops the command and everything it started, and tuios exits 124. A command stopped by a signal exits 128 plus the signal's number. - Each stream keeps its last 1 MiB. At most 8 run at once on one machine.
- The link needs
openin the host's policy, asnew-window --hostdoes. See What another machine may do here.
Without --host, tuios run -w PANE types the line at a pane's shell prompt here instead. See run.
Messages and files cross links too. Mail to a host whose link is down waits on this machine, under Waiting to send in the Inbox, and goes when the link is back. See Agent Messaging.
Agents on every linked host appear on the rail and in your Inbox, and fan, worktree and start-agent can run there. See Worktrees.
(Added in v0.9.3)
tuios cp copies files and folders between this machine and a host, or between two hosts. The daemon runs the copy. It goes on after you exit, after a dropped link and after a daemon restart.
tuios cp ./build.tar build: # to the receive folder on build
tuios cp build:~/logs ./ # a folder from build to here
tuios cp build:/var/log/app.log gpu:/tmp/ # from one host to anotherA path with HOST: in front is on that host. A path without it is on this machine. HOST: alone is the receive folder of the host. See tuios cp for every flag and exit code.
- TUIOS checks every file with sha256 before it puts the file in place. A file that does not match is copied one more time.
- A file that is there with the same bytes is never sent again. A second run of the same copy is a quick check.
- A folder copies with all that it holds. Small files go in one stream with a sha256 for each file, so a folder of thousands of files is fast on a slow link.
- A copy keeps the permission bits and the modification time of the original. It does not keep the owner.
- Links, named pipes, sockets and devices in a folder are not copied. The copy lists them as skipped.
- At most three copies move bytes at once. The others wait in the queue.
- A copy on a link waits behind your typing, so a large copy does not slow a pane.
A file there with different bytes follows the conflict policy. On a terminal, tuios cp asks for each file. Elsewhere, it skips the file. Pass --conflict skip, replace or keep-both to choose. Keep both names a copy from another machine report (from build).pdf.
When a machine goes away, the copy waits. When the machine is back, the copy goes on from where it stopped. A restart of the daemon does the same. --timeout 10m makes the command exit after ten minutes of waiting. The copy keeps waiting in the daemon.
--detach starts the copy and returns. Press Ctrl+C in a running tuios cp and choose k to leave the copy running. Follow, pause, resume, cancel and clear copies with tuios transfers. tuios hosts test build --speed measures how fast a copy can be.
On a terminal, tuios cp draws a progress block: a bar, the rate and the time left. In a pipe it prints plain lines. With --json it prints one JSON object on each line.
In the TUI, nothing shows while there is no copy. When there is one:
- The dock shows a bar and a percent.
- The rail row of the machine shows a percent mark.
- The Copies panel (Ctrl+B u) lists every copy with pause, cancel and retry.
- A notice shows when a copy ends.
The files list of the rail has Send to machine for a file. A file dropped on a pane on another machine asks whether to send it there.
You can also start a copy with the transfer-start verb. The transfer-list, transfer-pause, transfer-resume and transfer-cancel verbs control the copies. The file verbs also list, read, rename and remove files on a host.
The machine that receives a write decides where it may land. Each machine needs files in the other machine's allow list. A host lets a write land only in its files_roots: by default one receive folder, ~/Downloads/tuios. It never lets a write reach ~/.ssh, credentials or shell start files, and it never lets a read return keys, credentials, shell start files, or the data of browsers, mail and chat apps and crypto wallets. A folder copy leaves out the entries that the host denies. tuios cp then says how many items it did not copy, and exits with status 3. When a host refuses a copy, the error names the setting to change on that host. See Files over a link.
tuios hosts sync installs the TUIOS version of this machine on each host that runs another version. A release build sends its own release. --dev sends a build of a checkout, and --binary sends a file.
tuios hosts sync --dry-run # see what would change
tuios hosts sync --dev # install a build of this checkout on every host
tuios hosts sync build lab # only these hostsThe host needs no internet: sync sends the binary over ssh. It never uses sudo. It installs over the tuios on the host, or to ~/.local/bin/tuios when it cannot write that folder.
The daemon on a host keeps running the old version, and its sessions keep running. The row for the host gives the command that restarts it. Add --restart to restart the daemons in the same run. sync lists the sessions and the programs that a restart ends, and asks first. Without a terminal, add --yes. The sessions come back with their layouts and new shells.
See hosts sync for every flag.
A link reaches a host only when a TUIOS daemon runs there. When none runs, tuios hosts test build reports no_daemon and prints the command to run on the host:
build gaurav@buildbox no_daemon
The host is up and no tuios daemon is running on it.
To start the daemon, run this command on the host:
/home/gaurav/.local/bin/tuios start-server
Or start it from this machine:
tuios hosts test build --start
To start it from this machine, add --start. It runs that command over ssh and tests the host again. --dry-run shows the command and changes nothing.
# Start the daemon on build if it does not run
tuios hosts test build --start
# Install TUIOS on build if needed, then start it
tuios hosts sync build --starthosts test --start does not install TUIOS. On a host with no TUIOS, use hosts sync --start.
A link to a host that is up with no daemon keeps its ssh connection, and asks again over it on the same backoff. A daemon that starts there later is found with no new login. So an ssh agent that asks you for each key use, such as 1Password, asks once, not every minute. When the ssh connection drops, the link dials again as before. (Unreleased)
(Unreleased)
tuios daemon install-service starts the daemon when you log in, with no client: a systemd user unit on Linux (at boot, with linger), a launchd agent on macOS and a Task Scheduler task on Windows.
tuios daemon install-service
# The unit, and whether the running daemon is the service's
tuios daemon service-status
# Remove it, and leave the running daemon
tuios daemon uninstall-serviceThe service runs the daemon through your login shell, so panes get the login PATH. A crash restarts it. A tuios kill-server stop does not. A live upgrade keeps the same process, so the service sees no change.
With ssh_agent = "follow" on both machines and agent forwarding on the link, a session that you attach on a host uses the ssh agent of your client here. TUIOS does not forward the agent by default. Forward it only to a host you trust. See SSH Agent.
The [hosts] table on the machine a link arrives at also says what the machine of that name may do there. With no entry, a linked machine may list, send mail, open sessions and panes, type into panes, and read and write files (files). Answering prompts for you (respond) is off unless you allow it:
[hosts.laptop]
allow = ["list", "mail", "open", "write", "respond", "files"]
files_roots = ["~/Downloads/tuios", "~/dev"] # where it may write
hold_mail = true # hold its mail to agents here in your Inbox until you pass it on
[hosts."*"] # every machine with no entry of its own
allow = ["list", "mail"]Anything not allowed is refused with forbidden. See What another machine may do here for every capability and option.
- Sessions: Daemon sessions, detaching and resurrection
- Session Rail: Sessions grouped by machine
- Configuration: The hosts table and ProxyCommand transports
- SSH Agent: Forward your ssh agent to a host
- Web Terminal: Reach TUIOS from a browser instead
- Phones: Pair a phone with tuios pair
- Introduction
- Getting Started
- Learn tuios, hands on
- Keybindings
- Hints
- Finding a Pane
- Links
- TUIOS vs Others
Windows and Layout
Sessions and Machines
Agents
- Agents
- Inbox and Review
- Agent Messaging
- Program Status
- Worktrees
- Checkpoints
- Ship
- Push Notifications
- Turn Off Agent Features
- Task Boards
- Rex
Scripting
Recording
Reference
- CLI Reference
- Upgrading to v0.12.1
- Upgrading to v0.12.0
- Upgrading to v0.11.1
- Upgrading to v0.11.0
- Upgrading to v0.10.1
- Upgrading to v0.10.0
- Upgrading to v0.9.3
- Upgrading to v0.8.5
- Upgrading to v0.8.4
- Upgrading to v0.8.3
- Upgrading to v0.8.2
- Upgrading to v0.8.1
- Architecture
- Library Usage
- Contributing
- Brand and logo