Configuration

The other tables

The other tables: 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.

Keybindings: the [keybindings] table

leader_key

The prefix key. The default is ctrl+b.

[keybindings]
leader_key = "ctrl+a"

alt+space is already the app launcher.

opt+ and option+ mean alt+ on every platform, cmd+ and command+ mean super+, and control+ means ctrl+. See Modifier spellings. Press the leader two times in terminal mode to send it to the pane.

If TUIOS cannot read the leader, the leader is ctrl+b until you correct it. See When a key is wrong.

lock

Lock mode gives every key in terminal mode to the pane, except the leader.

[keybindings]
lock = true

This option is in the option reference: keybindings.lock.

See Lock mode.

nest_exit_key

The key that ends nest mode. The default is "f12". A key tuios cannot read goes back to "f12", and a key that programs type is reported as a problem.

Keybinding sections

Each section is a table under [keybindings]. Each action takes a list of keys. The Keybindings page lists every default.

SectionWhen it is active
window_managementWindow mode: windows, sessions, zoom, copy
workspacesWindow mode: switch and move between workspaces
layoutWindow mode: snapping, tiling, swaps, resizes, splits, preselect
mode_controlWindow mode: enter terminal mode, help, settings, quit
restore_minimizedWindow mode: restore a minimized window by number
systemWindow mode: the spotlight
navigationEmpty. Kept so older files still parse
terminal_modeTerminal mode, no prefix
globalBoth modes: the command palette and the launcher
prefix_modeAfter the leader key
window_prefixAfter leader, t
minimize_prefixAfter leader, m
workspace_prefixAfter leader, w
layout_prefixAfter leader, L
tape_prefixAfter leader, T
debug_prefixAfter leader, D
scriptWhile a tape plays
sidebarWhile the rail has the keyboard
sidebar_filesWhile the rail's cursor is on a file row. Checked before sidebar
sidebar_agentsWhile the rail's cursor is on an agent row. Checked before sidebar
inboxWhile the Inbox is open
inbox_peekWhile a prompt is open over the Inbox
mailWhile the mailbox is open
listsThe cursor keys of every list: the palette, the launcher, the pickers, the menus and the settings page. See List keys
guiKeys of the native GUI client. The terminal client does not read them

Key syntax

  • Modifiers: ctrl+, alt+, shift+, super+. Also opt+ and option+, which mean alt+, cmd+ and command+, which mean super+, and control+, which means ctrl+. These spellings work on every platform.
  • Special keys: enter, return, esc, escape, tab, space, backspace, delete, up, down, left, right, home, end, pgup, pageup, pgdown, pagedown, f1 to f12.
  • Any single character: letters, digits, symbols, and accented letters.
  • Held modifiers: leftalt, rightalt, leftctrl, leftsuper and the like, for hold_window_mode only. They need the Kitty keyboard protocol.

super+ only reaches TUIOS in terminals that speak the Kitty keyboard protocol. On Linux, opt+1 is alt+1. See One config on macOS and Linux.

[keybindings.window_management]
new_window = ["n", "ctrl+t"]   # several keys for one action
close_window = []              # no key: the key goes to the pane

An empty list is different from a missing line. A missing action gets its default back at the next load. An empty list stays empty.

shift+1 and ! are the same key, and so are shift+a and A. Binding one spelling binds both. Do not bind the two spellings to different actions.

Platform defaults

On macOS, the workspace and preselect defaults use opt+, and terminal_mode adds opt+tab, opt+shift+tab and opt+esc. Writing alt+ on macOS works but gives an advisory warning. Elsewhere the defaults use alt+. See Keybindings.

The [daemon] table

These options are in the option reference: daemon.agent_binaries, daemon.single_client, daemon.ssh_agent, daemon.display, daemon.respond_from_shell.

These options are in the option reference: daemon.log_level, daemon.agent_autodetect, daemon.agent_detect_seconds, daemon.agent_stall_seconds, daemon.subagent_fade_seconds, daemon.resume_agents, daemon.persist_scrollback, daemon.persist_scrollback_lines, daemon.persist_scrollback_kb, daemon.keep_awake, daemon.window_size, daemon.client_follows_upgrade.

A change to single_client, ssh_agent or display in the file applies to the next attach.

Daemon timings

The daemon's timings are whole seconds in [daemon], and 0 reads as the default. The daemon reads them when it starts. 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: false, no, off or 0 turns detection off.

These timings and limits have no environment variable. 0 reads as the default, and a value outside the range moves to the nearer end.

These options are in the option reference: daemon.save_seconds, daemon.exec_timeout_seconds, daemon.reconnect_seconds, daemon.host_heartbeat_seconds, daemon.host_heartbeat_timeout_seconds, daemon.host_call_timeout_seconds, agents.ask_wait_seconds, agents.undo_window_seconds, files.drop_keep_hours, files.drop_keep_mb.

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.

The display of the client

A daemon that a host link starts over ssh has no WAYLAND_DISPLAY or DISPLAY. Its panes have none either, so wl-copy, wl-paste, xclip and image paste fail. With display = "follow", the default, the new panes of such a daemon get the display of the local client that attached to the session or used it last.

[daemon]
display = "follow"
  • A daemon that has a WAYLAND_DISPLAY or a DISPLAY of its own keeps it. The option does nothing then.
  • Each session has a link to the Wayland socket of the client: wayland-<session id>.sock, in the folder of the daemon socket. A new pane gets WAYLAND_DISPLAY set to the full path of the link. The link moves to the socket of the newest client.
  • A new pane also gets DISPLAY and XAUTHORITY of the client. DISPLAY is 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. Run eval "$(tuios display-env 2>/dev/null)" in that shell, or add the line to your shell rc. See tuios display-env.
  • 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 attach and tuios new only. 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 of tuios-web.
  • A WAYLAND_DISPLAY name such as wayland-1 is looked up in the XDG_RUNTIME_DIR of the client, then in the one of the daemon, then in /run/user/<uid>. The client does not need XDG_RUNTIME_DIR.
  • The Wayland socket must be a Unix socket that you own. DISPLAY must be :N or :N.S, and tuios ignores a forwarded display such as localhost:10.0. XAUTHORITY must be a file that you own.
  • The option is read from the file only. tuios set-config cannot change it.

To change window_size for one session while it runs, use tuios set-config daemon.window_size smallest -s NAME. That value is not saved to the file. A change in the file applies when the daemon starts again.

tuios set-config daemon.log_level messages changes the level of a running daemon at once. verbose and trace also log pane content, window titles and paths. tuios logs reads the log.

The [startup] table

[startup] decides how a new session starts. It never changes a running session.

These options are in the option reference: startup.daemon, startup.tiled, startup.layout, startup.open_default_window, startup.start_in_terminal_mode, startup.session, startup.window.

When the file sets layout but not tiled = true, new sessions float and do not use the layout. TUIOS says so in the log viewer (Ctrl+B D l) and in tuios config apply: [startup] layout is set, but [startup] tiled is off, so new sessions float and do not use the layout. Set tiled = true to use the layout.

session and window change a plain tuios only. Other commands use the session you give them. session uses the daemon even when daemon is false.

--standalone and TUIOS_NO_DAEMON=1 override daemon for one run or one shell. If the daemon will not start, a bare tuios runs standalone and says so.

Older config files keep their behaviour. daemon and tiled default to true in a new install. A config file that already exists and does not mention them reads them as false, so an upgrade keeps the floating, standalone start it had. Add the keys to opt in.

In the same way, v0.8.0 changed eight appearance defaults: the rail is on, on the right, 24 columns wide; the dock and the window titles are on top; a zoomed pane takes 95% of the screen; a double click starts typing; and the scrollbar is a track. A config file that sets one of these keys keeps its value. The first-run file older releases wrote names most of them, so such an install keeps the old look until you remove those lines.

A session keeps its own layout once it is running. Attaching never rearranges a session to match your config.

The [workspaces] table

When the last pane on the workspace on screen closes, TUIOS shows the workspace you came from. This happens when the pane's program stops, when you close the pane, when tuios xpanes -ss closes it, and with tuios close-workspace.

These options are in the option reference: workspaces.return_when_empty, workspaces.new_window_when_empty.

TUIOS goes back in this order:

  1. For a workspace that tuios xpanes opened, the workspace where you ran tuios xpanes.
  2. The workspace you showed last that still has panes. After a chain of empty workspaces, TUIOS goes back past each one.
  3. The workspace with the lowest number that has panes.

When no workspace has panes, TUIOS shows the splash screen. The workspace on screen is the same for every client of the session, so every client goes back. A pane that moves to another workspace does not close, so TUIOS does not go back.

[workspaces]
return_when_empty = false

The daemon reads the setting when it starts and when the file changes. tuios set-config workspaces.return_when_empty false changes it while TUIOS runs.

A pane on an empty workspace

By default, a workspace with no panes shows the splash screen. To open a pane there when you switch to it, as tabs do in other multiplexers, turn on new_window_when_empty:

[workspaces]
new_window_when_empty = true

The new pane starts in the folder of the pane that had focus on the workspace you came from. It starts in the session's start folder (the folder that tuios new --cwd gave) when you came from a workspace with no pane, from a scratch terminal, or from a pane on another machine. With appearance.new_window_follow_ssh = true, a pane that runs ssh gives a new pane that runs the same ssh, as the new-window key does.

A pane opens only when you switch: with a workspace key, a click on the dock, go-to, the pane navigator or the command palette. These switches do not open a pane:

  • move_and_follow and other moves that take a pane with them.
  • tuios xpanes, tuios select-workspace, tuios run-command and tape scripts.
  • The switch back that return_when_empty makes.
  • The start of TUIOS and an attach to a session.

A workspace gets one pane, also when two clients switch to it at the same time. When you switch away before the pane opens, you stay where you went.

Each client reads the setting from its config file, and a change applies at once. The settings page lists it under Daemon, and tuios set-config workspaces.new_window_when_empty true changes it while TUIOS runs.

The daemon must be from the same release or newer. An older daemon opens no pane. Run tuios restart-server to load the new daemon.

The [launcher] table

The app launcher starts a desktop entry in a new pane. A graphical program opens its own window, so its pane stays empty. Set launcher.gui_command to start such an entry with another command. The launcher adds the entry's argv to that command. Entries with Terminal=true and programs from $PATH still open in a pane.

[launcher]
gui_command = "tuios-wayland launch --"   # or "niri msg action spawn --"

Use a command that runs an argv. Do not use a command that joins its arguments into a shell line, such as swaymsg exec -- or hyprctl dispatch exec. With such a command, the text of a desktop entry becomes shell code. Any installed package can write a desktop entry.

launcher.keep_open keeps the pane of a launched program open after it exits. A line under the output shows the exit status. The option needs a daemon session.

[launcher]
keep_open = true

The [tape] table

[tape] controls project tapes: a .tuios.tape file in a directory. See Tape Scripting.

These options are in the option reference: tape.autorun, tape.auto_review.

A tape edited after you trusted it is untrusted again.

The [debug] table

These options are in the option reference: debug.show_key_events.

--show-keys and Ctrl+B D k toggle the same overlay. See Showkeys.

The [screenshot] table

[screenshot] sets the defaults for tuios screenshot and the in-app capture (Ctrl+B C). Each key has a command flag that overrides it for one capture.

These options are in the option reference: screenshot.format, screenshot.directory, screenshot.copy, screenshot.preview, screenshot.frame, screenshot.background, screenshot.padding, screenshot.radius, screenshot.shadow, screenshot.controls, screenshot.title_format, screenshot.font_family, screenshot.font_file, screenshot.scale, screenshot.cursor.

[screenshot]
format = "svg"
frame = "plain"
background = "none"
padding = 24

png and svg carry the frame. ansi and txt are plain output, so the frame keys do not apply.

The [screensaver] table

[screensaver] animates the screen after a period with no input. It is off by default.

These options are in the option reference: screensaver.enabled, screensaver.idle_minutes, screensaver.effect, screensaver.while_busy.

[screensaver]
enabled = true
idle_minutes = 5
effect = "matrix"

There are 36 effects. tuios list-options screensaver.effect prints them. A plugin can add a saver: set effect = "plugin/ID/SAVER". See A screen saver in a plugin. The settings page previews each effect on your current screen.

S in window mode starts the screen saver now, whatever enabled says.

The [hints] table

[hints] sets what hints mode (Ctrl+B F) labels.

This option is in the option reference: hints.patterns.

These options are in the option reference: hints.builtins, hints.alphabet, hints.open, hints.dim, hints.all_panes.

See What hints mode finds for the pattern names.

The [panes] table

[panes] sets the keys of the pane labels (Ctrl+B Q) and the first layout of the pane navigator (Ctrl+B /).

These options are in the option reference: panes.label_keys, panes.navigator_layout, panes.navigator_search, panes.drag_and_drop, panes.drag_and_drop_desktop.

With drag_and_drop on, a program that speaks the protocol, 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, quoted for its shell, by the rules of a drag from the rail. tuios reads no file, and refuses a drop back into the pane the drag came from. The switch is off because the protocol is still settling.

Drag and drop with the desktop

Set drag_and_drop_desktop = true with drag_and_drop = true to drag files between the desktop and the panes. The terminal that tuios runs in must speak the same protocol. Today that is kitty 0.47 or later. tuios asks the terminal once at startup.

[panes]
drag_and_drop = true
drag_and_drop_desktop = true
  • From the desktop: drag a file from a file manager or a browser onto the tuios window. It lands on the pane under the pointer. A program that speaks the protocol takes it. Any other pane gets the path as a paste, by the rules above.
  • To the desktop: a file that a program in a pane drags, such as yazi, becomes a drag on the desktop. Drop it on any other window. The desktop shows the file names and the pane they come from.
  • tuios takes a drag only when the press went to a pane that offers drags. You still move a pane, select text and drag a row of the rail as before.
  • The bridge is for a terminal on this machine. A client over SSH, through tuios-web, or attached to the daemon of another machine does not use it.
  • Both switches apply without a restart.

The [path_picker] table

[path_picker] sets show_hidden. With true, the path picker shows the names that start with a dot when it opens. The default is false.

The [worktree] table

[worktree] path sets where tuios worktree new, New worktree... on the rail and tuios fan put a worktree. The value is a path template. Empty is the default. See Where a worktree goes.

[worktree]
path = "{{ repo_path }}/.worktrees/{{ branch | slug }}"

The [review] table

[review] sets how a review opens.

These options are in the option reference: review.focus, review.scope.

[review]
focus = "files"
scope = "uncommitted"

base shows the changes since the base. In a plain repository, the base is the merge base with the upstream branch, so commits that you did not push yet are part of the review. uncommitted shows only the changes that are not committed. In the review, u still switches between the two, and b still sets another base. The compare view of two attempts does not use scope.

Both keys are on the settings page, in the Behavior section. tuios set-config review.scope uncommitted applies from the next review. tuios reads another value as the default and shows a warning when the config loads. tuios set-config refuses it.

The [tasks] table

[tasks] sets how the task board works.

This option is in the option reference: tasks.stages.

These options are in the option reference: tasks.auto_stage, tasks.attachment_max_mib, tasks.attachments_per_card, tasks.attachment_session_mib, tasks.machine_cap.

[tasks]
stages = ["todo", "doing", "verify"]
auto_stage = false
machine_cap = 4
attachment_max_mib = 4
attachments_per_card = 10

A file over a limit is refused with an error that names the option. See Attachments.

The dispatch settings (mode, preset, caps, quiet hours, verify) are not in the config file. tuios task dispatch sets them, and the daemon saves them. See Dispatch.

The [files] table

[files] sets the copies that o on a file of another machine makes here, in the rail's files section.

These options are in the option reference: files.open_copy_ask_mb, files.open_copy_max_mb, files.open_copy_keep_days.

Shell prompt marks: the [shell] table

TUIOS turns on OSC 133 prompt marks in the bash and zsh shells it starts in panes, as Ghostty and kitty do. The marks say where a prompt starts, where a command starts, and how it ended. tuios run, wait-for command-finished, capture-pane --last-command, the scrollback browser and copy mode read them. A pane with marks also keeps one copy of its prompt when you make the pane narrower.

TUIOS does not change your files:

  • zsh starts with ZDOTDIR set to a folder of TUIOS's own. Its .zshenv sets ZDOTDIR back to your value, reads your .zshenv, and adds the marks. zsh then reads your .zprofile, .zshrc and .zlogin as usual.
  • bash starts with --rcfile set to a file that reads your ~/.bashrc and then adds the marks. Your PS1, PROMPT_COMMAND, traps and set -e stay as they are. This needs bash 4.4 or newer.
  • fish 4 and nushell send the marks themselves, so TUIOS adds nothing. Other shells start as they are.

When your own prompt already sends a mark, TUIOS does not send that mark again. A shell starts less than 1 ms slower. To turn it off:

[shell]
integration = "off"   # default: "auto"

The change applies to new panes. tuios new-window --shell-integration off chooses for one pane, and tuios doctor shell shows which panes send marks. A pane that runs ssh, or a window on another machine, gets no marks from TUIOS: add the lines tuios doctor shell prints to the rc file there.

The [scratch] table

[scratch] sets the size of the scratch terminal that Ctrl+B g shows in a popup. See Scratch terminal.

These options are in the option reference: scratch.width, scratch.height.

The old session key is no longer used. TUIOS ignores it, and the config warnings tell you to remove it.

The [pip] table

[pip] sets the size and the first corner of the picture-in-picture view. See Picture in picture.

These options are in the option reference: pip.width, pip.height, pip.corner.

The [paste_buffers] table

[paste_buffers] sets how many paste buffers the daemon keeps. The daemon reads it when it starts and when the file changes.

These options are in the option reference: paste_buffers.limit, paste_buffers.max_kb.

A smaller limit removes the oldest buffers at once. A yank larger than max_kb does not become a buffer, but it still goes to the clipboard.

Command keys

[[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 Command keys.

Actions and menus of your own: the [[actions]] and [menus] tables

[[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 Your actions.

[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 Your menus.

The [spotlight] table

[spotlight] lights one part of the screen and dims the rest, for screen sharing. B in window mode, or Ctrl+B B in any mode, turns it on and off. While it is on, Esc in window mode or a click on the Spotlight chip in the dock turns it off. See Spotlight.

These options are in the option reference: spotlight.enabled, spotlight.follow, spotlight.radius, spotlight.dim, spotlight.edge, spotlight.shake.

follow = "cursor" sends fewer bytes to a remote client.

The [dock] table

[dock] sets what the bar draws: three ordered lists of component names, plus a table for each component that needs one. Edit it in the file, or with the Dock > Components editor on the settings page. set-config cannot change the lists.

[dock]
left   = ["mode", "workspaces", "trail", "tape"]
center = ["windows"]
right  = ["transfers", "notifications", "copy-help", "cpu", "ram", "clock", "session-controls"]

[dock.clock]
format = "15:04"

[dock.custom.branch]
command  = "git branch --show-current"
refresh  = "event:after-focus-change"
on-click = "tuios new-window log -- git log --oneline -20"

These lists are the default. A missing list uses the default. An empty list (left = []) draws nothing on that side.

The built-in components are mode, workspaces, trail, tape, windows, transfers, notifications, copy-help, cpu, ram, clock, session-controls and session. Listing one lets it draw. It still needs its own condition, so cpu still needs show_cpu. copy-help shows the keys of copy mode, multi copy mode and hints mode while the mode is open. See Mode keys in the dock.

session-controls shows an agents button when the session has an agent pane. The button opens the agents view, the same as Ctrl+B i. When agents wait for you, the button shows how many in the attention colour.

transfers shows the copies between machines. It shows nothing while no copy exists. One copy is a bar and a percent, [####--] 61%. More copies are a count and a percent, 3 copies 42%. waiting means a link is down. 1 failed stays until you open the Copies panel. A click opens the Copies panel.

[dock.clock] takes format, a Go time layout. A layout without seconds refreshes once a minute. session shows the session name, the workspace and the pane, such as main 2:1. It is in no default list. [dock.session] takes format, with {session}, {workspace} and {pane}. It also takes the cell style keys fg, bg, bold, cap_left and cap_right. [dock.custom.NAME] takes the same style keys. Colours are #rrggbb. When the center list has a clock or a custom cell, the centre is at the middle of the terminal. A notification does not move it, and it does not shorten the minimized pane labels. On a crowded bar, the centre moves left to keep the cells on the right on the screen. Click a cut notification to read the full message.

Custom components

[dock.custom.NAME] defines a cell. Put custom/NAME in a list to place it.

These options are in the option reference: dock.custom.NAME.command, dock.custom.NAME.refresh, dock.custom.NAME.on-click, dock.custom.NAME.max-width, dock.custom.NAME.fg, dock.custom.NAME.bg, dock.custom.NAME.bold, dock.custom.NAME.cap_left, dock.custom.NAME.cap_right.

With push, the command keeps running and each line it prints replaces the cell. With event:, the command runs again when the daemon reports one of those hook events.

A component whose command fails is hidden. tuios list-dock-components shows what each component last did and why a cell is missing. tuios refresh-dock [name] runs a component again now.

A command runs in the client, with a three second timeout. TUIOS reads at most 64 KiB of its output and stops the command when it prints more. SGR colour stays. TUIOS removes other control sequences, C1 controls, bidirectional and invisible characters, and bytes that are not UTF-8. Wide characters and emoji stay.

SSH server limits: the [ssh] table

The [ssh] table sets the limits of the tuios ssh server. The server reads it when it starts. The defaults do not stop a normal login.

[ssh]
handshake_timeout = "120s" # time to finish the login; 0 turns the limit off
idle_timeout = "0"         # close a connection with no traffic for this long; 0 is off
max_handshakes = 32        # connections that log in at the same time; 0 is no limit
max_sessions = 64          # sessions open at the same time; 0 is no limit

These options are in the option reference: ssh.handshake_timeout, ssh.idle_timeout, ssh.max_handshakes, ssh.max_sessions.

A duration is a value such as 90s, 30m or 2h. A value that does not parse, or a negative value, gives a warning and the default. tuios ssh --handshake-timeout, --idle-timeout, --max-handshakes and --max-sessions replace these values for one run. The server writes the limits it uses to its log when it starts. tuios set-config cannot change this table.

The [hosts] table

[hosts] names the other machines this daemon links to. Each host is a table.

[hosts.build]
addr = "gaurav@buildbox"

[hosts.work]
addr = "workstation"
connect_timeout = 5

These options are in the option reference: hosts.NAME.addr, hosts.NAME.connect_timeout, hosts.NAME.command, hosts.NAME.ssh_options, hosts.NAME.repos_root.

You can also manage the table from the shell. These commands edit the file:

tuios hosts add build gaurav@buildbox
tuios hosts test build
tuios hosts remove build

A change that gives a machine less applies at once, also on links that are open. A new host, a host that dials another way, or a change that gives a machine more waits for tuios config apply from a terminal outside TUIOS. A daemon restart also applies it. So tuios hosts add from a pane waits. A host that you add with "Add a host" on the settings page applies at once. See Changes that wait.

Rules for ssh_options

ssh_options accepts only options that cannot run code or write files on this machine. Write each option as -o Keyword=value, with one plain value and no quotes.

  • Accepted examples: -p, -i, -l, -J, Port, User, HostName, HostKeyAlias, IdentityFile, StrictHostKeyChecking, the ServerAlive options and the algorithm lists.
  • Refused: ProxyCommand, LocalCommand, the known hosts files, ControlPath, -F and socket forwards.
  • Refused: port forwards (-L, -R, -D).
  • -J and ProxyJump take host names only. ForwardAgent takes only yes or no.
  • A host addr or command cannot start with a dash.

TUIOS drops a host with a refused option. tuios hosts and the Inbox name the reason. Put a refused option in ~/.ssh/config, and name that host in addr.

[hosts.build]
addr = "gaurav@buildbox"
ssh_options = ["-J", "bastion", "-o", "ServerAliveInterval=30"]

Upgrading from v0.8.0. After the upgrade, look in the Inbox or run tuios hosts. A host with a refused option is dropped. Move the option, such as ProxyCommand or LocalForward, into ~/.ssh/config. Keep port forwards in ~/.ssh/config too.

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.

A machine with files can read your files and write new ones. Three keys in its [hosts.NAME] table set the limits:

[hosts.laptop]
allow = ["list", "files"]
files_roots = ["~/Downloads/tuios", "~/dev"]   # where it may write
files_read_roots = ["~/share"]                 # where it may read
files_min_free = "5GiB"                        # the space a write must leave free

These options are in the option reference: hosts.NAME.files_roots, hosts.NAME.files_read_roots, hosts.NAME.files_min_free, hosts.NAME.files_max_entries.

A path is absolute or starts with ~. Some places are always closed, whatever the roots say:

  • Writes never go into ~/.ssh, ~/.gnupg, cloud and git credentials, shell start files such as .bashrc and .zshrc, login items, crontabs, /proc, or tuios's own config and state.
  • Reads never return keys, credentials, keyrings, shell histories, browser profiles, /proc, or tuios's own state. A public *.pub key in ~/.ssh is the one exception.
  • Reads also never return ~/.gitconfig, ~/.config/git, shell start files or ~/.config/environment.d. The list also covers the snap and flatpak browser folders, Thunderbird, Signal, Discord, Slack, Telegram, VS Code and common crypto wallets. A folder copy over a link leaves these entries out.
  • A file with more than one name (a hard link) is never read over a link. Copy it to a new file to share it.

The read rules and files_read_roots also apply to a kitty image that a program names by path in a pane that runs on this machine for the other machine. See Kitty images in the pane.

A refused write says where writes may land and which key to change. A deny list can never name every secret on a machine, so files_read_roots is the stronger choice.

Other limits:

  • One machine may have at most 8 write streams and 64 unfinished copies here at once. Past that, a write is busy, and a copy waits and tries again.
  • Files dropped on a pane go to a private drop folder. It holds at most 256 MiB for all drops, for 24 hours.
  • A copy another machine starts here keeps to the same rules, also after tuios restarts. When files is taken away, its copies here stop.
  • A change that widens files_roots or files_read_roots, removes files_read_roots, or lowers files_min_free waits for tuios config apply. A change that narrows applies at once.
  • A file that another machine writes here gets the sender's permission bits under this machine's umask. It never gets group or world write. The execute bits stay. This holds for a paired device too.
  • A machine with files cannot write the config folders of the agent tools that tuios integrates. It also cannot read the logins and API keys of more agent tools and cloud tools.

Give files only to machines you trust. A machine with files can write any file inside its roots and read any file outside the deny list. A file copy can run code: a binary in a folder on your PATH, or a config file that a program reads. Give files, and a wide files_roots, only to a machine you trust as you trust your own.

See Remote Hosts for the copies themselves.

Using a linked host

Once a host is linked, you can list its sessions and agents (tuios ls --all-hosts, tuios list-agents --host build), attach to or create sessions on it (tuios attach --host build api, tuios new --host build), and open a pane whose process runs there (tuios new-window --host build). See tuios hosts.

Reaching a host you cannot ssh to directly

A host behind NAT, with no port forward and no jump host, is a network problem to solve under TUIOS. Any tool that pipes stdio to a remote port works as an ssh ProxyCommand. ssh_options refuses ProxyCommand, so name it in ~/.ssh/config.

Tailscale's tailcat is one such tool. It carries a connection over WireGuard with no Tailscale account and no open port. Run it on the far side against sshd:

tailcat --serve=22

Then add a host to ~/.ssh/config that uses it:

Host laptop-tailcat
    HostName laptop
    User gaurav
    ProxyCommand tailcat <token> 22

Name that host in the host entry:

[hosts.laptop]
addr = "laptop-tailcat"

ssh still decides who may connect: the tunnel only carries bytes to sshd, which asks for your key as usual. A leaked tailcat token gives reachability, not access. TUIOS adds no identity system of its own and opens no listening port.

The [tailscale] table

[tailscale] changes which tailnet machines tuios hosts add and tuios hosts tailnet offer as addresses. It never adds a host by itself.

These options are in the option reference: tailscale.enabled, tailscale.addr, tailscale.user, tailscale.users, tailscale.os, tailscale.offline, tailscale.self, tailscale.shared, tailscale.include, tailscale.exclude, tailscale.max, tailscale.socket.

[tailscale]
user = "ubuntu"
exclude = ["*-pad-*"]

[tailscale.users]
build = "admin"

The [agents] table

[agents] sets how TUIOS treats the coding agents in its panes. Except for enabled, it is outside list-options, and set-config cannot change it, so a program in a pane cannot loosen it. The daemon reads it at start and again whenever the file changes. See Inbox and Review for what each part does.

Agents that stop reporting

A hooked agent reports at each prompt and each tool call. When an agent that reported working sends no report for silent_after, tuios shows it as unknown with the reason silent. Its row reads "No report for N min".

[agents]
silent_after = "10m"   # default; "0" or "off" turns it off

The value is a Go duration, such as 90s or 20m. A value that does not parse reads as 10m, with a warning. The daemon reads the value when it starts and when the file changes. See Agents that stop reporting.

Card preview

Space on a card of the task board shows the card whole. card_preview says where:

[agents]
card_preview = "auto"     # "side", "sheet", "auto" or "off"
card_preview_width = ""   # the side panel: cells ("70") or a share ("40%"); empty is 40%

side puts it in a panel beside the columns, sheet over them, and auto beside them on a screen 140 columns or wider that keeps three columns, over them otherwise. off never shows it. The panel is 40% of the view by default, at least 44 and at most 96 cells. A drag on its edge sets the width, and the view keeps it. A double click on the edge gives the width back to card_preview_width.

The other agent tables

[agents.approvals]
enabled = ["claude-code", "opencode"]   # harnesses whose permission prompts the Inbox may answer
hold_seconds = 120                      # 10 to 300
hold_plans = true                       # a plan follows enabled

[agents.approvals.risk]
builtin = true                          # keep the shipped risk rules
panes_may_allow = false                 # a pane with the respond grant may not allow a risky call

[[agents.approvals.risk.rule]]
name = "kubectl apply"
tools = ["Bash"]                        # empty: every tool
pattern = '\bkubectl\s+(apply|delete)\b'   # RE2, matched per command

[agents.permissions]
mode = "strict"                         # open (default) or strict
grants = ["read", "write", "fan"]       # what a pane holds under strict

[agents.recap]
mode = "toast"                          # toast, inbox or off
away = "10m"
test_patterns = ["go test", "pytest"]

[agents.queue]
max = 8                                 # at most 64

[agents.mail]
wake = true                             # type one line into an idle agent with unread mail

[agents.checkpoints]
enabled = true
keep = 50                               # at most 1000
max_untracked_mb = 50                   # a negative value means no limit

These options are in the option reference: agents.approvals.enabled, agents.approvals.hold_seconds, agents.approvals.hold_plans, agents.approvals.risk.builtin, agents.approvals.risk.panes_may_allow, agents.approvals.risk.rule, agents.permissions.mode, agents.permissions.grants, agents.recap.mode, agents.recap.away, agents.recap.test_patterns, agents.queue.max, agents.mail.wake, agents.mail.questions_to_parent, agents.checkpoints.enabled, agents.checkpoints.keep, agents.checkpoints.max_untracked_mb, agents.presets.NAME.

After turning on approvals.enabled, run tuios integration install for that harness again, so its hook is the version that waits. The grants are read, write, fan, respond, files and admin. See What a pane may do.

A change to [agents.permissions] that gives panes less applies at once. A change that gives more, such as strict to open, waits. Run tuios config apply from a terminal outside TUIOS, or restart the daemon. See Changes that wait.

The [notify] table

[notify] sends a push notification when the Inbox gets an item that waits for you. The daemon sends it, so it works when no client is attached. The providers are ntfy, Pushover and a webhook.

[notify]
web_url = "https://term.example.com/"   # tuios-web, for a link to the item

[notify.ntfy]
url = "https://ntfy.sh/a-long-random-topic"
token_file = "~/.config/tuios/ntfy-token"   # optional

These options are in the option reference: notify.enabled, notify.web_url, notify.content, notify.quiet_active_seconds, notify.cooldown_seconds, notify.max_per_hour, notify.allow_http_redirects.

[notify.triggers] selects the Inbox kinds: approval, plan, question and ask are on by default, mail, errored and finished are off. Like [hosts], [notify] is not in list-options, and tuios set-config cannot change it. A new address or a new source for a secret waits for tuios config apply from a terminal outside TUIOS. tuios notify test sends a test notification through each provider. See Push Notifications for the providers and the secrets.

Web Push

[notify.webpush] configures the pushes the daemon sends to a phone that registered for Web Push. It needs no provider.

[notify.webpush]
subject = "https://example.com/tuios-contact"   # optional
allow_insecure = false

These options are in the option reference: notify.webpush.subject, notify.webpush.allow_insecure.

See Push Notifications.

Hooks: the [hooks] table

[hooks] runs shell commands on window, workspace, session and agent events. Event names use hyphens, such as after-new-window. See Hooks and tuios list-hooks.

[[links.rules]] turns text in a pane into a link: regex is a regular expression in Go syntax, and url is the address a match opens. $0 is the whole match, and $1, $2 or ${name} are its groups. A real URL wins over a rule, and an earlier rule wins over a later one. See Link rules.

The [mermaid] table

[mermaid] sets the colours and the background of tuios mermaid. See Mermaid diagram colours.

The [plugins] table

[plugins] says which plugins tuios runs.

These options are in the option reference: plugins.enabled, plugins.dirs.

See PLUGINS.md.

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.

On this page