Files, input and focus
Files, input and focus: part of the Configuration of TUIOS.
This page is one part of docs/CONFIGURATION.md of the tuios repository. The Configuration page lists every part.
Sidebar file editor
Settings, Sidebar, File editor sets appearance.sidebar.editor, the terminal
editor command used by Shift+Enter on a text file. For example:
[appearance.sidebar]
editor = "micro"Other terminal editors and arguments work too, such as nano or vim -f.
Quote a path or an argument that contains spaces. tuios splits the command into
arguments and runs no shell. It adds the full path of the file at the end. If
the value is empty, tuios uses $EDITOR, then $VISUAL, then vi. File links,
paths and hints open a file in quick look, and e there opens it with the same
command, at the line on top for vi, Emacs, nano, kakoune and helix. tuios reads the first 512 bytes of
a file to check that it is text. It refuses binary files and special files.
Every table of config.toml has a section on this page. Tables lists them.
[notifications] sets how many seconds a message stays up. duration is for info and success messages, and its default is 2. warning_duration (default 8) and error_duration (default 15) are for warnings and errors. Any value from 1 to 3600 is valid, and 0 uses the default. tuios warns about a negative value and uses the default. tuios warns about a value above 3600 and uses 3600. style sets how a message looks. full (the default) shows a coloured bar on the left of the message and a line above it that counts down. plain shows the icon and the text only. The icon keeps its colour, so an error still looks different from an info message. level sets the least severe message the dock shows: info (the default) shows every message, warning only warnings and errors, and error only errors. A message the dock does not show still goes to the log viewer (Ctrl+B D l), so the notice for a key that did nothing can be read there. Set log_hidden = false to keep those messages out of the log as well. Warnings and errors always go to the log. A message from a pane, an agent or mail does not use level. [notifications.agent] and [notifications.mail] control those messages.
machine_offer (default true) shows a message when a pane logs in with ssh or mosh to a machine that no [hosts] entry reaches. The message is "buildbox is not a machine here. Add it?" with three choices. Add opens a new pane that runs tuios hosts setup for the machine. Not now hides the message for that machine until tuios starts again. Never adds the machine to a list in sidebar.json, and the Alerts tab of Settings shows that list. Select a machine in that list to remove it. A message that gets no answer goes away after duration, as Not now does. The message shows only for a login that reads your keys: a tunnel (-N, -f, -n, -W), -s, -T and a remote command without -t do not count. ssh that scp, rsync, git, sftp or sshfs starts does not count. The client must run for 5 seconds. This machine on port 22 and the git hosts (github.com, gitlab.com, bitbucket.org, codeberg.org) are never offered. The check works with [agents] enabled = false. Set machine_offer = false to turn it off.
[notifications.mail] has enabled, notify, dock, sound and between_agents. Each key except between_agents follows the same key in [notifications.agent] while it is unset, so a config without the table alerts as before. between_agents (default false) also alerts on a message from one agent to another. Sound mode, cooldown, cue files and quiet hours always come from [notifications.agent]. tuios set-config notifications.mail.KEY "" clears a key, and tuios get-config then prints (follows notifications.agent.KEY).
tuios list-options describes every settable path with its type, default, and accepted values or range, straight from the registry the validator uses. A number that counts something says what: 200 ms, 2 cells, 45% (the unit field of list-options --json), and the settings page shows the same unit after the value. The in-app settings page (Ctrl+B ,) edits and persists the same options, and its rows are derived from that same registry: an option an agent can set is an option a person can reach, and a test fails the build if one is not.
Sidebar peek
When you put the pointer on a session row in the sidebar, the terminals
section shows the panes of that session. When you move the rail cursor onto a
session row, the same thing occurs. This is the peek. To turn it off, set
appearance.sidebar.peek to false:
[appearance.sidebar]
peek = false # true is the defaultWith the peek off, the terminals section shows the panes of the attached
session. It changes only when you attach to a different session. The setting
also shows in Settings, Sidebar, and tuios set-config appearance.sidebar.peek false changes it while tuios runs.
Split the config into several files
You can keep part of the config in other files. Use this to share one config.toml between machines and keep the settings for one machine, such as its hosts, in a separate file. A Nix or home-manager setup can also put its settings in a file that it manages, and leave config.toml to tuios.
There are two ways to add files. Use one or both.
-
Put an
includelist at the top of config.toml, before the first table:include = ["hosts.toml", "~/.config/tuios/local.toml", "?work.toml"]A relative path is relative to the file that has the
includeline.~is your home directory. A name that starts with?is optional: when the file is not there, tuios says nothing. An included file can have its ownincludelist.On Windows, write an include path with forward slashes, or put it in a single-quoted literal string. In a double-quoted TOML string, a backslash starts an escape:
include = ["C:/Users/me/tuios/local.toml", 'C:\Users\me\tuios\work.toml'] -
Put
*.tomlfiles in aconfig.ddirectory next to config.toml. tuios reads them in name order, so10-theme.tomlcomes before50-hosts.toml.
Which value wins
tuios reads the files in this order. A later file wins over an earlier file.
- The files in the
includelist, in list order. An included file's own includes come before it. - The files in
config.d, in name order. - config.toml.
config.toml wins, and it holds only what you changed. On the first start,
tuios writes a config.toml with comments and no settings. The one exception
is [startup]: tuios writes tiled = true and daemon = true there, unless
another file sets them. Each change from tuios adds or changes only the key
you changed. So an included file applies everywhere except where you chose a
value of your own.
A config.toml from an older tuios sets every key, and so it hides every other
file. Run tuios config prune to remove the keys that have their default
value. When another file sets one of those keys, its value then applies. The
command lists those keys and asks before it changes the file. Use
tuios config prune --dry-run to see the keys and --yes to skip the
question. A run with no terminal needs --yes.
The files merge with these rules:
-
Tables merge key by key, at every depth.
[hosts.NAME]tables merge by name, so each file can add its own hosts. -
For a single value, the later file wins.
-
An array of values replaces the earlier array. It does not add to it.
-
An array of tables, such as
[[keybindings.command]], merges entry by entry. It is never replaced whole. A later entry matches an earlier entry bynamewhen both have a name, and bykeywhen they do not. A matched entry merges key by key. An entry that matches nothing goes at the end. -
To remove an entry that an earlier file sets, add an entry with the same
nameorkeyanddisabled = true:[[keybindings.command]] name = "deploy" disabled = true
A relative file path in an included file, such as a [plugins] dirs entry or
a token_file, is relative to that file.
These are not errors:
- An include that names a file that does not exist. tuios shows a warning and skips it, so one machine can include a file that only it has.
- An include cycle, or a file that includes itself. tuios shows a warning and reads each file once.
- An optional include or a
config.dfile that tuios cannot read, such as a link that points to itself. tuios shows a warning and skips it. A required include that tuios cannot read stops the load. - An
includekey below a table header. TOML puts it in that table, so it includes nothing. tuios shows a warning.
An include that names a directory stops the load. Put a directory of files in
config.d. A file that exists and has a TOML error also stops the load, the
same as an error in config.toml.
Find where a key comes from
tuios config files # every file, in merge order
tuios config origin # every key and the file that sets it
tuios config origin appearance.theme # one keytuios config origin also names the earlier files that set the same key. Their
values lose.
Hot reload
tuios watches every file it reads: config.toml, each included file, each file
in config.d, and the config.d directory itself. When a file is a link,
tuios also watches the file that the link points to. A save to any of them
takes effect at once. An included file that was missing applies when you make
it, if its directory exists.
tuios config apply makes the daemon and every tuios client on this machine
apply the files as they are now. Use it when a save does not reach a client,
for example when you make an included file in a new directory. It also loads
the daemon's [hooks] table, so a hook change needs no restart. See
HOOKS.md.
Where tuios writes a change
The settings page, tuios set-config, the keybind manager,
tuios keybinds unbind, tuios hosts add and tuios plugins write the config.
They write only the keys you changed, and never copy the other files into
config.toml. A change made while a file changed on disk keeps the new values
of that file. Each change goes to one file:
- A key that a file sets goes to the last file that sets it. The look file,
config.d/look.toml, is not a target: a change to a key that it sets goes to config.toml. See Looks. - A new entry in a table of entries, such as a new
[hosts.NAME], goes to the last writable file that has entries in that table. - Any other new key goes to config.toml.
- A removed key is removed from each file that sets it.
tuios changes only the lines of the key, so the comments, the blank lines and the line endings of the file stay. A comment above a table stays with that table. tuios never writes a file you wrote again from its values. When it cannot express a change in the lines of an included file, it writes the change to config.toml and tells you. When it cannot remove a key that way, the save fails and the message names the file. Only config.toml itself is written again whole in that case, without its comments.
tuios never writes a read-only file. This includes a file that Nix or
home-manager links in from the store. When a read-only file sets the key,
tuios writes the change to config.toml and tells you. When config.toml is
read-only too, tuios writes the change to the last writable file that config.toml
includes. The change must go to a file that comes after every file that sets
the key. If there is no such file, the save fails and the message names the
file to change. tuios cannot remove a key from a read-only file. It removes an
array entry with a disabled = true entry in a writable file. When an entry
that tuios writes must not take keys back from an earlier file's entry, tuios
writes a disabled = true entry first and the new entry after it.
tuios config reset writes the first-start config.toml again, with your
include list, and lists the other files that still apply. When config.toml
has an error, the reset still keeps an include list that it can read.
One config on macOS and Linux
You can share one config.toml between a Mac and a Linux machine, for example with a dotfiles repo. tuios reads opt+ and option+ as alt+ on every platform. On Linux, a key such as opt+1 is alt+1.
The [keybindings.terminal_mode] table also accepts middle for the middle
mouse button, with ctrl, alt or shift, such as ctrl+middle. A program
that uses the mouse gets a plain middle press.
tuios ignores a key that it cannot read and loads the rest of the file. The action gets its default key when it has no other key. If another action already has that default key, the action has no key. tuios shows a config problem when it starts, and the log viewer (leader D l) names each key and its file. tuios keybinds doctor and tuios config apply list these keys too. A table under [keybindings] that tuios does not have, such as [keybindings.terminal] for [keybindings.terminal_mode], is a config problem too: tuios ignores every binding in it, and the log viewer and tuios config apply name the table and the table you most likely meant.
Keyboard layout and Option characters
[keybindings]
keyboard_layout = "us" # us, other
option_glyphs = "auto" # auto, alt, bind, typeThese options are in the option reference: keybindings.keyboard_layout, keybindings.option_glyphs.
See Shifted digits and AZERTY and One Option key for typing.
Lock mode
[keybindings]
lock = trueThis option is in the option reference: keybindings.lock.
See Lock mode.
Nest mode
[keybindings]
nest_exit_key = "f12"
[keybindings.prefix_mode]
nest = ["enter"]This option is in the option reference: keybindings.nest_exit_key.
See Nest mode.
Opening links
tuios finds two kinds of link in a pane. An OSC 8 hyperlink is a link that a
program marked, such as ls --hyperlink, gcc, delta, gh or an agent
CLI. Its text and its target can be different. A bare URL is plain text that
starts with http://, https://, ftp://, ftps://, file://, ssh:// or
git://. Hints mode and the pointer use the same URL detector. With
links = "all", a file path that is there is a link too, and opens in quick
look (see Paths in a pane or the agents view).
[appearance]
links = "all" # off, marked (OSC 8 only), all
link_click = "both" # both, ctrl, shift, off
link_hover = "safe" # safe, always
link_opener = "" # for example "firefox --new-tab" or "open -a Safari %s"These options are in the option reference: appearance.links, appearance.link_click, appearance.link_hover, appearance.link_opener.
The system opener is open on macOS, rundll32 on Windows, wslview under
WSL, and xdg-open on other systems. tuios runs no shell. It gives the URL to
the opener as one argument. If the opener fails, tuios shows a message and
puts the URL on your clipboard.
Link rules
A link rule turns plain text that is not a URL into a link, such as a ticket ID that opens its page in an issue tracker. It works like WezTerm's implicit hyperlinks.
[[links.rules]]
regex = '\b([A-Z][A-Z0-9_]+-[1-9][0-9]*)\b'
url = "https://jira.example.com/browse/$1"regexis a regular expression in Go syntax.urlis the address a match opens.$0is the whole match, and$1,$2and so on are its groups. A named group is${name}. A group followed by a letter, a digit or_needs braces: write${1}_x, because$1_xnames a group called1_x. tuios warns about a url that names a group the regex does not have.- Keep the scheme and the host fixed in
url, and put groups in the path or the query only, as in the example. A group before the path, such ashttps://example.com$1, lets the text on screen choose the host. - A match is a link like a bare URL: the hover underline and label (which
shows the address), the click in
link_click,link_opener, the OSC 8 output to your terminal, andCtrland a label in hints mode. A label withoutCtrlcopies the text on screen. - Rules apply when
linksisall, as bare URLs do. - A real URL wins when a rule matches text inside it. An earlier rule wins over a later one.
- The address a rule builds goes through the same check as every link. A rule
whose address is not
http,https,mailto,ftporftps, or that holds a byte a bare URL cannot hold (a space, a quote, a backtick, an angle bracket,|,^,{,},\or a control character), makes no link. - A rule that does not compile, or that matches empty text, is skipped, and tuios shows a warning when it reads the config.
- With rules, tuios reads every line of a pane for them, not only the lines
that hold
://. With no rules, nothing changes. - As with bare URLs, the OSC 8 output carries the rule links of the focused pane only. In another pane they are found on hover and click.
Which machine opens the link
- A local client opens the link on your machine.
- Under
ssh, tuios does not use the system opener, because it would open the browser on the remote machine. tuios puts the URL on your clipboard. Set$BROWSERorlink_openerto a command that forwards the URL, if you have one. - A remote client (
tuios ssh, the web client) puts the URL on your clipboard. - A Linux machine with no
DISPLAYand noWAYLAND_DISPLAYhas no desktop. tuios puts the URL on your clipboard.
In all these cases, tuios also sends each link to your terminal as OSC 8. Use the link click of your terminal to open it on your machine.
Safety
- Only
http,https,mailto,ftpandftpslinks go to the opener. tuios copies other links, such asjavascript:,data:or the scheme of an application. - A
file://link opens in an editor pane only when the file is on this machine. Afile://link with the name of another host does not open. - tuios refuses an address with control characters or spaces.
- The hover label shows the target. After a click, the message names the host. tuios does not ask before it opens a link. The label and the scheme list give the protection, and a prompt on each click teaches people to accept it.
OSC 8 in the output of tuios
tuios draws each pane into its own frame, so your terminal sees the output of
tuios and not the output of the program. tuios writes every link in the
focused pane as OSC 8. An OSC 8 link keeps its URI and its id=. A bare URL
gets an id= from tuios, so a URL that wraps to the next row is one link.
Your terminal can then show and open the real target. In a pane that is not
focused, tuios writes the OSC 8 links of the program. Your terminal finds the
bare URLs itself.
Terminals
A terminal sends a click to tuios only when the terminal does not use the
click itself. Most terminals keep Shift+click for their own selection when
a program reads the mouse. That is why Ctrl+click is the main click.
| Terminal | Shift+click gets to tuios | Ctrl+click gets to tuios | The terminal opens OSC 8 links |
|---|---|---|---|
| kitty | No. kitty opens the URL under the pointer. | Yes | Yes, with Shift+click or Ctrl+Shift+click |
| Ghostty | No. Ghostty extends its selection. | Yes. On a link, Ghostty opens it. | Yes, with Ctrl+click (Linux) or Cmd+click (macOS) |
| WezTerm | No. Shift bypasses mouse reporting. | Yes | Yes |
| Alacritty | No. Alacritty opens a hinted URL. | Yes | Yes, with Shift+click |
| foot | No. Shift bypasses mouse reporting. | Yes | Yes, in URL mode (Ctrl+Shift+O) |
| iTerm2 | Yes | Yes | Yes, with Cmd+click |
| Windows Terminal | No. Shift bypasses mouse mode. | Yes | Yes, with Ctrl+click when it gets the click |
| xterm | No. Shift bypasses mouse reporting. | Yes | No |
Cmd is not part of the mouse protocol, so tuios never sees Cmd+click. On
macOS, Cmd+click opens a link through the terminal, from the OSC 8 that
tuios writes. In Ghostty, a program can ask for Shift+click with
XTSHIFTESCAPE, or you can set mouse-shift-capture = true. tuios does not
ask, because that takes Shift selection away from you.
Pause focus follows mouse
appearance.focus_follows_mouse = true focuses the pane under the pointer as
the mouse moves. Set appearance.focus_follows_mouse_pause to hold a key that
pauses it:
[appearance]
focus_follows_mouse = true
focus_follows_mouse_pause = "ctrl" # ctrl, alt, or off (the default)- Hold the key and move the mouse. The focus stays on the current pane.
- Release the key. The next mouse move focuses the pane under the pointer.
- The key still goes to the pane. A program that reads the mouse gets the
motion with the key on it.
Ctrl+drag andAlt+drag work as before.
tuios reads the key from the mouse reports that your terminal sends. Most
terminals send Ctrl and Alt. Shift is not a choice, because most terminals
keep Shift with the mouse for their own selection. On macOS, some terminals
use Option with the mouse for their own actions. If alt does not work in
your terminal, use ctrl.
Neovim pane navigation
appearance.nvim_navigation is false by default. Set it to true to enable
pane navigation through the optional
tuios-nvim-navigator plugin:
[appearance]
nvim_navigation = trueSee KEYBINDINGS.md for the matching focus-key mappings and protocol behaviour.
Wrap focus at the edge
appearance.focus_wrap is false by default. Set it to true to wrap
directional focus at the edge of a tiled layout, as tmux select-pane does:
[appearance]
focus_wrap = trueWhen no pane is in that direction, focus goes to the pane on the far side that faces the focused pane. If more than one pane is on the far side, tuios picks by the rule of a normal focus move. A pane that fills the layout in that direction keeps focus.
The option applies to every directional focus move in a tiled layout:
- The focus keys in window mode, in terminal mode and after the prefix.
- The Neovim navigator hand-back, when
nvim_navigationis on. tuios focus-window --directionand theFocusDirectiontape command.
In the scrolling layout, up and down wrap inside the column. Left and right move along the strip and do not wrap. With tiling off, focus does not wrap. The tmux shim always wraps, as tmux does, and does not read this option.
persist_scrollback in [daemon] (default true) saves each pane's history with its session. After a daemon restart or a reboot, the restored pane shows that history above a dim divider, and the new shell starts under it. persist_scrollback_lines (default 1000) and persist_scrollback_kb (default 2048) set the most lines and the most KiB one pane saves. The files hold what your panes printed, secrets included. Set persist_scrollback = false to stop this. The next time the daemon starts, it deletes the history it saved before. See SESSIONS.md.
The daemon's timings are in [daemon] as whole seconds. 0 is the default.
The daemon reads them when it starts, and each has an environment variable,
read at the same time, that wins over the file:
These options are in the option reference: daemon.agent_detect_seconds, daemon.agent_stall_seconds, daemon.subagent_fade_seconds, daemon.cleanup_seconds, daemon.pr_poll_seconds, daemon.transfer_keep_seconds, daemon.dispatch_ready_seconds.
agent_autodetect reads TUIOS_AGENT_AUTODETECT the same way. A client reads
TUIOS_CLEANUP_SECONDS too, for its own buffers.
These timings and limits have no environment variable. 0 is the default, and
a value outside the range moves to the nearer end.
| Option | Default | Range | What it sets |
|---|---|---|---|
[daemon] save_seconds | 30 | 10 to 600 | The longest a session whose panes printed waits to be saved. It keeps each pane's folder current for a restore. A change to the layout is saved within 2 seconds either way. |
[daemon] exec_timeout_seconds | 30 | 0 to 3600 | How long a command run with tuios exec may take when the caller names no timeout. |
[daemon] reconnect_seconds | 15 | 0 to 300 | How long a client waits for a restarted daemon before it gives up. A daemon that stopped without saying so is waited on for at most 6 seconds. |
[daemon] host_heartbeat_seconds | 15 | 0 to 300 | How long a link to another machine may carry nothing before the daemon pings it. |
[daemon] host_heartbeat_timeout_seconds | 5 | 0 to 60 | How long one ping waits for its reply. Two misses in a row end the link. |
[daemon] host_call_timeout_seconds | 8 | 0 to 120 | How long one listing over a live link may take before the link is dialed again. |
[agents] ask_wait_seconds | 120 | 0 to 3600 | How long tuios ask-human waits for your answer when the agent names no timeout. The question stays in the Inbox after the wait. |
[agents] undo_window_seconds | 10 | 0 to 300 | How long after a dismiss, a snooze or a queued reply u takes it back. |
[files] drop_keep_hours | 24 | 0 to 8760 | How long a file dropped into a pane of another machine stays in that machine's drop folder. |
[files] drop_keep_mb | 256 | 0 to 65536 | The most MiB the drop folder holds. A drop that does not fit is refused. |
The daemon reads them when it starts. The client reads reconnect_seconds and
undo_window_seconds from its own config, and a change applies at once. The
time a dial to one machine may take is connect_timeout in that machine's
[hosts.NAME] table.
client_follows_upgrade in [daemon] (default true) makes a client on this machine follow a live upgrade (tuios daemon upgrade). When the new image takes the session back and its build is newer than the client's, the client runs the binary the upgrade named, as tuios attach on the same terminal. The session, its panes and the flags you started the client with stay. A client of another machine, over ssh or in a browser, keeps its build. Set it to false to keep the old client running; it then says that it still runs the old build.
window_size in [daemon] sets the size of a session that has more than one client. The names are the names of the tmux window-size option. See SESSIONS.md.
| Value | Size of the session |
|---|---|
latest (default) | The client that last had input. A smaller client shows a part of the session. |
smallest | The smallest client. Every client shows the full session. |
largest | The largest client. A smaller client shows a part of the session. |
A client that is larger than the session fills the space the session does not use with dots. A line in that space names the client that sets the size. The rail and the dock stay at the edges of each client's screen.
To change the value of one session while it runs, use tuios set-config daemon.window_size latest -s NAME. The value is not saved to the config file. A change in the config file applies when the daemon starts again.
single_client in [daemon] (default false) keeps one client for each session. When a client attaches, every other client of that session detaches. The newest attach wins. Each detached client exits with status 0 and prints "Another client attached to this session." The session continues to run. This is tuios attach -d on every attach. Two attaches do not detach the other clients: a view-only client, such as tuios-web --read-only, and the attach that tuios makes on its own to get a session back after a host link drops. A change in the config file applies to the next attach.
[daemon]
single_client = truessh_agent in [daemon] (default "off") can be "follow". Then each session has a stable link to the ssh agent socket of the client that attached to the session or used it last. When you ssh to the machine with agent forwarding and run tuios attach, your panes use the agent of that ssh connection.
[daemon]
ssh_agent = "follow"- The link is
agent-<session id>.sockin the folder of the daemon socket, for example$XDG_RUNTIME_DIR/tuios/agent-3f2a9c1d-0b7e-4d0a-9c4e-5a1f2b3c4d5e.sock.tuios ssh-agent-pathprints it. - Each new pane of the session gets
SSH_AUTH_SOCKset to the link. - A shell that started before you set the option keeps its old value. To use the link in that shell and in every shell, add this line to your shell rc:
p=$(tuios ssh-agent-path 2>/dev/null) && export SSH_AUTH_SOCK="$p" - When the client that the link points at detaches, the link moves to the socket of the client before it. When no attached client has a socket, the link points at the
SSH_AUTH_SOCKof the daemon, if the daemon has one that passes the checks below. Otherwise tuios removes the link. - The daemon removes its links when it stops and when you set the option to
"off". At start, it removes the links that a stopped daemon left. - tuios uses the
SSH_AUTH_SOCKoftuios attachandtuios newonly. A client that runs inside a pane does not count. tuios finds such a client by its process, so a process that leaves its pane on purpose (for example, withsetsidand a clean environment) can still move the link. This check stops mistakes and agents, not a local process that wants to get past it. - tuios resolves a symbolic link once, so
~/.ssh/agent.sockand the 1Password agent work. The link then points at the real socket. The real socket must be a Unix socket that you own. Every folder above it must be owned by you or by root, and no other user can write to it, unless it is sticky like/tmp. tuios refuses other sockets. - A client of the tuios SSH server or of
tuios-webhas no agent socket, so it does not move the link. To follow your agent, ssh to the machine withssh -Aand runtuios attach. - The agent can follow you to a remote host too. Turn on
ssh_agent = "follow"on both machines, and turn on agent forwarding for the link to that host. UseForwardAgent yesfor the host in~/.ssh/config, orssh_options = ["-A"]under[hosts.NAME]. tuios does not forward the agent by default. The daemon keeps one link for each such host,agent-link-<host>-<hash>.sock. The host name is in lower case and cut to 32 characters, and the hash is of the exact name, so two hosts never share a link. It points at the agent of the person on this machine who attached a session on that host, or typed in one, last. A session of this machine does not move it. The daemon starts the link ssh to that host withSSH_AUTH_SOCKset to that link. On the host, the panes of a session you attach through the link use the forwarded agent. - tuios decides that a host forwards from what
ssh -Gprints for its address with itsssh_options. That is how ssh itself reads the options and~/.ssh/config. tuios asks again when the config changes, and whenssh -Gfailed the last time. A host that leaves the config takes its link with it. - Before any client attaches a session on a forwarding host, its link points at the daemon's own
SSH_AUTH_SOCK. If the daemon has none, or its socket fails the checks above, the panes on that host have no agent until a client attaches. The link ssh to a host that does not forward starts with the environment of the daemon, unchanged. Without forwarding, the panes on the host use theSSH_AUTH_SOCKthat their own login there sets: the agent of the daemon on the host, or one from keychain or gnome-keyring through PAM, or none. - If the link to a host shares an ssh master connection, ssh forwards the agent of that master.
- Forward the agent only to a host you trust. Root on the host can use a forwarded agent to sign in to other machines as you while the link is up. If the host pins the hub with
restrictinauthorized_keys, addagent-forwardingto the options of that key.
A change in the config file applies to the next attach. New panes get the link while the option is on.
display in [daemon] (default "follow") can be "off". A daemon that started without a display has no WAYLAND_DISPLAY or DISPLAY. This happens when a host link starts the daemon over ssh. With "follow", the panes of such a daemon get the display of the local client that attached to the session or used it last. Then wl-copy, wl-paste, xclip and image paste work in the panes when you attach from the desktop.
[daemon]
display = "follow"- A daemon that has a
WAYLAND_DISPLAYor aDISPLAYof its own keeps it. Its panes get the daemon's values, and the option does nothing. - Each session has a link to the Wayland socket of the client:
wayland-<session id>.sockin the folder of the daemon socket. A new pane getsWAYLAND_DISPLAYset to the full path of the link. - The link moves to the socket of the newest client. A pane that started under one desktop client still reaches the display after that client detaches and another attaches.
- A new pane also gets
DISPLAYandXAUTHORITYof the client.DISPLAYis a name, not a path, so a pane keeps the value it started with. - A shell that started before a desktop client attached has no display. To get the display in that shell, run this line. To get it in every shell, add it to your shell rc:
eval "$(tuios display-env 2>/dev/null)" - When the client detaches, the session uses the display of the client before it. When no attached client has a display, tuios removes the link, and new panes get no display.
- tuios uses the display of
tuios attachandtuios newonly. The client must run on this machine, as your user, and outside every pane. tuios ignores a client that comes through a host link, a client of the tuios SSH server and a client oftuios-web. WAYLAND_DISPLAYcan be a full path or a name likewayland-1. tuios finds a name in theXDG_RUNTIME_DIRof the client, then in the one of the daemon, then in/run/user/<uid>. The client does not needXDG_RUNTIME_DIR.- The Wayland socket must be a Unix socket that you own. Every folder above it must be owned by you or by root, and no other user can write to it, unless it is sticky like
/tmp. DISPLAYmust be a display on this machine,:Nor:N.S. Its socket/tmp/.X11-unix/XNmust be owned by you or by root. tuios ignores a forwarded display such aslocalhost:10.0.XAUTHORITYmust be a file that you own, in folders that pass the same checks.- The daemon removes its links when it stops and when you set the option to
"off". At start, it removes the links that a stopped daemon left.
keep_awake in [daemon] (default "off") keeps the machine from sleeping while agents work.
| Value | The machine stays awake |
|---|---|
off (default) | Never. The machine sleeps as its own settings say. |
agents | While an agent pane on this machine has the state working. |
on | While the daemon runs. |
[daemon]
keep_awake = "agents"- The daemon holds the machine awake, so it works when no client is attached, over ssh, and on a host.
- On Linux the daemon runs
systemd-inhibitfor idle and sleep.systemd-inhibit --listshows atuiosrow while it holds. On macOS it runscaffeinate. On Windows it callsSetThreadExecutionState. - Only sleep is held off. The display can still dim and lock. On a Mac, a closed lid still sleeps.
- A pane whose program runs on another machine, in a global session, does not count. That machine runs the agent.
- With
[agents] enabled = false, no agent works, soagentsholds nothing. - The daemon does no work while nothing changes. It counts the working panes only when the state of a pane changes or a pane closes.
- When the daemon stops, or a live upgrade replaces it, the hold ends. The new daemon takes it again.
tuios keep-awake agentssets the value, applies it at once and saves it to the config file.tuios keep-awakeshows the hold.tuios doctor keep-awakechecks that this machine can be held awake. The Daemon tab of the settings has the same option. A change in the config file applies at once.
[hints] sets what hints mode (Ctrl+B F) labels. See HINTS.md.
[panes] sets label_keys, the keys that the pane labels (Ctrl+B Q) use. The default is 1234567890. Letters a to z and digits are allowed. See KEYBINDINGS.md.
[panes] also sets navigator_layout, the layout the pane navigator (Ctrl+B /) opens in: tree, flat or cards. The default is tree. Press v in the navigator to change the layout. navigator_search = true opens it ready to type a search, and esc with nothing typed closes it. See KEYBINDINGS.md.
[panes] drag_and_drop = true turns on drag and drop between panes over the kitty drag and drop protocol (OSC 72). A program that speaks it, such as yazi 26.9 or later, can drag files from its pane: hold the left button on a file in terminal mode and carry it to another pane. A pane whose program speaks the protocol takes the drop itself. Any other pane gets the paths as a paste, by the rules of dragging a file into a pane below: quoted for the shell in the pane, and refused, with the reason in the label, when that pane could not use a path on this machine. The same rules hold the pane the drag starts from. Dropped text, as against paths, goes only into a pane whose program turned bracketed paste on. tuios reads no file for either side and refuses a drop back into the pane the drag came from. The default is false. The protocol is kitty's and still settling, so the switch is off until it is asked for.
[panes] drag_and_drop_desktop = true, with drag_and_drop, bridges drags to and from the desktop when tuios runs in a terminal that speaks the same protocol itself: kitty 0.47 or later. tuios asks its terminal once at startup and, when it answers, registers as a program that takes drops and offers drags. A file dragged from a file manager or a browser onto the tuios window then lands on the pane under the pointer, by the rules above: a program that speaks the protocol takes it itself, any other pane gets the path as a paste. A file a program in a pane drags, from yazi say, becomes the desktop's drag and can be dropped on any other window; the drag image the desktop shows is the file names and the pane they come from. While the bridge is up the terminal recognises the drag gesture and tuios answers only one whose press went to a pane that offers drags, so moving a pane, selecting text and dragging a row of the rail are as they were. The bridge is for a terminal on this machine: a client over SSH, through tuios-web or attached to another machine's daemon does not register. Both switches take effect without a restart: turning the bridge off takes the registration back, turning it on asks the terminal again. The default is false.
[path_picker] sets show_hidden. With true, the path picker (Alt+;) shows the names that start with a dot when it opens. The default is false. Alt+H in the picker shows or hides them. See KEYBINDINGS.md.
Open files from the sidebar
o in the sidebar's files section opens the selected file or folder. tuios uses
the system opener: xdg-open on Linux, open on macOS, wslview under WSL,
and the program for the file type on Windows.
Add [[files.open]] rules to use another program for some files:
[[files.open]]
match = "*.pdf"
command = ["zathura", "{path}"]
[[files.open]]
match = "*/" # every folder
command = ["thunar", "{path}"]- tuios uses the first rule that matches. With no match, it uses the system opener.
matchis a glob. Case does not matter. A pattern with no/matches the file name. A pattern with a/matches the full path, for example"/home/me/papers/*.pdf".- A
/at the end of the pattern matches folders only. A pattern without it matches files only. commandis a list of words. tuios starts it directly, with no shell.{path}in a word becomes the path. With no{path}, the path goes last.- tuios starts the command on the machine that runs the client. For a file in a listing of another machine, it opens a copy here. See the next section. It does not open a file for a remote client.
- When the program stops with an error in the first 3 seconds, a message says so. The log has the reason.
- tuios skips a rule with no pattern, a pattern that is not a valid glob, or no command, and shows a warning for it when it starts.
appearance.link_openerand$BROWSERdo not apply to files. They name a browser for web links.
Open a file of another machine
o on a row of a listing of another machine shows a message: "notes.md is on
build. Click to open a copy here." Click it, or press the prefix and then j,
to copy the file or folder here and open the copy. Press esc to say not now.
- The copy goes to
~/.cache/tuios/opened/HOST/HASH/NAME, or under$XDG_CACHE_HOMEwhen it is set. The hash is of the host and the far path, so the same file always goes to the same place. - The copy uses the same engine as
Sandtuios cp. It shows in the Copies panel. - When the far file did not change since the last copy,
oopens the copy here at once. When it changed, tuios copies it again. When the copy here changed too, tuios keeps it and opens it. Runtuios transfers clear-openedto get a new copy. - tuios does not send changes back. Changes to the copy stay here.
- A folder is copied with all it holds. tuios does not copy links, so a link cannot bring in a file from outside the folder.
- Above 200 MiB, or above 1000 files, tuios shows the size and asks again.
Above 4096 MiB, or above 20000 files, it does not copy. Press
Sto send it to a folder here instead. - tuios replaces each character that a file name cannot hold with
_. A name such as..\..\xstays in the folder of its copy. - tuios deletes a copy that nobody opened for 7 days when the daemon starts,
and each time
omakes a copy.tuios transfers clear-openeddeletes them all now.
[files]
open_copy_ask_mb = 200 # ask first above this size, in MiB
open_copy_max_mb = 4096 # do not copy above this size, in MiB
open_copy_keep_days = 7 # -1 keeps every copyDrag a file into a pane
appearance.sidebar.file_drag lets you drag a row of the files section onto a
pane. The pane gets the path, quoted for the shell in the pane. It is on by
default. I on a row does the same for the focused pane, with this option on
or off. See
KEYBINDINGS.md.
[appearance.sidebar]
file_drag = false[scratch] sets the size of the box in which Ctrl+B g shows the scratch terminal. The old session key is no longer used. See SESSIONS.md.
[pip] sets the size (width, height, border included, default 40x12) and the first corner (default bottom-right) of the picture-in-picture view that p pins. See SESSIONS.md.
[[keybindings.command]] binds a key to a command that you write: a scratch terminal, a popup, a pane or a command with no window. A mistake in an entry is a warning, and tuios ignores that entry. See KEYBINDINGS.md.
[[actions]] declares an action of your own, user:NAME: a built-in action, a program with its arguments (placeholders such as {pane.cwd} fill one argument each, and no shell reads them), or a plugin action. A key, a menu row or tuios actions run runs it. See KEYBINDINGS.md.
[menus.NAME] declares a menu: a title and a list of rows, each an action or a submenu with an optional key, label and when. open_menu:NAME opens it, as a which-key panel from a key and in place from a right-click menu. The target names (pane, session, file and the others) are the shipped right-click menus: add puts rows after the row after names, remove takes rows out, and items replaces them. An action's targets and when decide where its row shows. See KEYBINDINGS.md.
Configuration
Every table and option in the TUIOS config.toml, with defaults and how changes apply.
Motion, rendering and themes
Motion, rendering and themes: part of the Configuration of TUIOS.
tuios lives only at tuios.dev and github.com/Gaurav-Gosain/tuios. tuios has no X or Twitter account. An account that offers a tuios token or presale is not this project.