Configuration

Permissions and other machines

Permissions and other machines: 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.

What a pane may do

Every pane holds grants that say what a process in it may do through tuios: read (its own session and fan group), write (type into its own session, into panes that hold nothing it does not), fan (write in its fan group and start agents), respond (answer prompts without you, and type into a pane waiting on one), files (copy files with tuios cp, see below) and admin (everything else, as before grants). A pane started with --grants (tuios start-agent, fan, new-window) or given grants with tuios set-pane-grants holds those. Every other pane holds the default this table sets:

[agents.permissions]
mode = "strict"
grants = ["read", "write", "fan"]

mode is open, the default, or strict. Under open a pane holds admin, so every script in a pane works as it always has. Under strict it holds grants, which is read, write and fan when unset; an empty list gives nothing but the right to report about itself. Any other mode is read as strict, and an unknown grant is dropped: both are reported as config warnings, and both fail toward less. admin never includes respond, and no default gives it, so listing respond here is how you let every pane answer prompts for you.

files lets a pane copy files without admin. A copy may start when each end on this machine is inside the pane's folder (its worktree, else its working folder). Each end on a host must be under its home folder, or be its receive folder. The pane sees and controls only the copies it started. admin includes files. To let every pane copy near its work under strict, add it to the list:

[agents.permissions]
mode = "strict"
grants = ["read", "write", "fan", "files"]

task lets a pane add, claim and finish the task cards of its own session (tuios task) without admin. A pane claims only for itself and changes only the card it holds. admin includes task. Under strict, give it to the panes that take work from a conductor:

[agents.permissions]
mode = "strict"
grants = ["read", "write", "fan", "task"]

The daemon reads the table when it starts and again when the file changes. A change that gives panes less reaches every pane on the default at its next call. A change that gives more, such as strict to open, waits, because a process in a pane can write config.toml. Run tuios config apply from a terminal outside tuios to apply it, or restart the daemon. Until then the daemon logs it, and tuios pane-grants says so. When a start finds that panes hold more than at the last run, it says so in the log, in tuios pane-grants and in the Inbox. Like [agents.approvals], it is not in list-options and tuios set-config cannot change it, so no pane can loosen it. The paste buffers hold what you copied, so a pane needs read to read them, write to change them, and both to paste one. AGENT_STATE.md has the whole model.

SSH server limits

The [ssh] section 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
  • handshake_timeout: The server closes a connection that does not log in within this time. It is the same as LoginGraceTime in OpenSSH. The limit ends when the login is complete, so it does not close a session that you use.
  • idle_timeout: The server closes a connection after this time with no traffic in either direction. It is off by default. A session that shows a clock or other output that changes stays open.
  • max_handshakes: When this many connections are logging in, the server closes a new connection at once. A connection that is logged in does not count.
  • max_sessions: When this many sessions are open, over all connections, the server refuses a new session. The client sees a message. The refused session does not attach to a session and does not open a pane.

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.

Like [hosts], the section is not in list-options, and tuios set-config cannot change it.

Move between machines

The next_host and prev_host keybind actions go to a session on the next or the previous machine: this machine first, then the [hosts] table. They have no default key. See KEYBINDINGS.md.

[keybindings.window_management]
next_host = ["alt+."]
prev_host = ["alt+,"]

What another machine may do here

A [hosts.NAME] table names a machine this one links to. Read on the machine a link arrives at, the same table also says what the machine of that name may do there:

[hosts.laptop]
addr = "laptop"                  # optional: without it nothing is dialled
allow = ["list", "mail", "open", "write", "respond"]
hold_mail = true
hosted_grace = "10m"

[hosts."*"]                      # every machine with no table of its own
allow = ["list", "mail"]

allow is the capabilities, and anything not in it is refused with forbidden and nothing done:

CapabilityWhat it lets the other machine do here
listRead: sessions, windows, captures, screenshots, agent state, the Inbox, prompts, waits and the event stream. It also gives a live stream of the bytes of any pane (stream-pane).
mailSend and read agent mail, and use the stash.
openStart processes: sessions, windows, worktrees, fans, start-agent, clones of a repository by its URL, and panes this machine runs for it.
writeChange what is here: type into panes, run a line at a prompt, close and move windows, set options, layouts and names, report agent state, and attach. Also read a worktree's work out with bundle-worktree (tuios worktree pull), since a machine that may type into a shell here can read those files already.
respondAnswer for the person: prompts, held approvals, ask-human questions, dismissing Inbox items, and passing on held mail. Also type into a pane that waits on a prompt, from a pane on the other machine. The person on the other machine, outside every pane, needs only write for that.
transcriptsRead the conversation of an agent here, from the person's own client attached over the link. The client must send the nonce of its attach: an agent in a pane, a link the other machine did not vouch for, and a caller with no nonce are refused. respond includes it.
filesRead and write files here with the file verbs: a file's bytes, copies in and out (transfer-start on the other machine), new folders, moves and removes. It is apart from write, so you can stop one machine's copies and keep its typing. A write that arrives over the link lands only in the folders of files_roots (the receive folder unless you add more, see below), and the drop folder for dropped files, never in ~/.ssh, ~/.gnupg, credentials, shell start files, login items or tuios's own config, whatever allow and files_roots say. A read never returns keys or credentials. It also lets a window here that the other machine draws show kitty images that a program names by path (kitten icat --transfer-mode=file): this machine reads the file under the same read rules and files_read_roots, and sends the bytes. See protocol.md.

With no table, a machine may list, mail, open, write, files and transcripts. respond is opt-in. Relaying on to this machine's own hosts needs the five capabilities a link had before files (list, mail, open, write, respond), because the next machine sees the relay as coming from this one; a table written for an older tuios that allows those five still relays. A copy this machine runs for another one also needs files. A table that sets allow without files keeps that machine from the file verbs. An allow that is set replaces the inherited list; allow = [] allows nothing but hello.

Where a link may write: files_roots. A machine with files writes only under the folders files_roots names, plus the drop folder. Unset, it is one receive folder: ~/Downloads/tuios on macOS and Windows, and $XDG_DOWNLOAD_DIR/tuios (or ~/Downloads/tuios) on other systems. tuios makes it on first use. Widen it on purpose, per machine:

[hosts.laptop]
allow = ["list", "files"]
files_roots = ["~/Downloads/tuios", "~/dev"]

A path is absolute or starts with ~. files_roots = ["~"] lets the machine write anywhere in your home folder; the deny list below still holds inside every root, so even then it cannot touch ~/.ssh, a shell start file, or the config folders of the agent harnesses tuios integrates (Claude Code, Codex, Gemini CLI, opencode, Cursor and the others), which name commands those tools run. A write outside the roots is refused, and the refusal says where writes may land and which setting to change. A reload that widens files_roots, like one that widens allow, waits for tuios config apply.

The mode of a file a link writes. A file that another machine writes here gets the sender's permission bits under this machine's umask, as cp and scp without -p do. It never gets group or world write. The execute bits stay, so a script stays runnable. This holds for a paired device too.

Where a link may read: files_read_roots. Unset, a machine with files reads any file you can read, apart from the read deny list: keys, credentials (also the logins and API keys of agent tools such as Gemini CLI, opencode, Qwen Code, Kilo, Pi, oh-my-pi, Hermes, Amp and the Copilot CLI, Cursor's MCP servers, the sops age keys, atuin's key and history, Ollama's key, and the OCI, doctl and ngrok credentials), shell start files, ~/.gitconfig, keyrings, shell histories, browser profiles, /proc and tuios's own state. A deny list can never name every secret on a machine. Set files_read_roots to hold reads to the folders you name, plus the folders the machine may write. That is the stronger choice:

[hosts.laptop]
files_read_roots = ["~/share"]

The rule covers file-read, file-preview, file-hash, file-walk, a copy out, and the names and sizes file-stat and file-list show. The read deny list still holds inside every root. A file with more than one name (a hard link) is never read over a link, inside a root or outside one. Copy it to a new file to share it. A reload that removes or widens files_read_roots waits for tuios config apply. A reload that narrows it applies at once.

How much a link may write. A write over a link must leave files_min_free free on its disk: "1GiB" unless you set it. The value is a whole number with B, KB, MB, GB, TB, KiB, MiB, GiB or TiB. "0" turns the check off, and a reload that lowers it waits for tuios config apply. A write that does not fit is refused as disk_full before a byte moves. One machine may have at most 8 write streams and 64 unfinished part files here at once. Past that, a write is busy, and a copy waits and tries again.

A machine may also make at most files_max_entries new files and folders here in ten minutes: 20,000 unless you set it. An empty file uses no bytes, so files_min_free does not stop a machine from making millions of them. Past the bound, a new file or folder is busy, and a copy waits and goes on. The count goes down evenly over the ten minutes. A folder copy of 20,000 files lands at full speed, and a larger one goes on at about 33 files a second. 0 turns the bound off. A reload that raises it waits for tuios config apply. The drop folder holds at most 256 MiB for all drops together, and a machine writes there only inside a drop that file-drop-dir made.

[hosts."*"]
files_min_free = "5GiB"
files_max_entries = 50000

A copy that another machine starts here with transfer-start or drop-files is held to these rules too, also after tuios restarts. When a reload or a restart takes files away from that machine, its copies here stop.

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

hold_mail holds mail from that machine to any agent here in your Inbox, marked held for NAME, until you pass it on with p there (or release-agent-message). Mail to you is yours already and is not held.

hosted_grace is how long a pane this machine runs for the other one (a window opened with --host there) outlives a dropped link, still running and keeping its last 64 KB of output, waiting to be reattached: a Go duration, "0" to end it with the link as before, 10 minutes when unset, at most 24 hours. See Limits.

Each field inherits from [hosts."*"], which inherits from the default. The name is matched without regard to case. It is the one the other machine gives for itself, its host name up to the first dot, unless the ssh key it logs in with pins one:

command="tuios stdio-proxy --as laptop",restrict ssh-ed25519 AAAA...

Only a pinned name is a boundary: a key that may run any command can run a shell, and can claim any name. A pinned name needs a table of its own. A key pinned to a name with no [hosts.NAME] table may do nothing here, so a key that outlives its table does not get [hosts."*"] or the default. A table with a policy and no addr is not dialled and not listed by tuios hosts, and [hosts."*"] never is.

The daemon follows the file. A change that gives a machine less applies to the next call on every link, including links already open. A change that gives a machine more, a new host, or a host that dials another way waits for tuios config apply from a terminal outside tuios, or a daemon restart. tuios hosts add applies its change that way, so from a pane it waits. tuios hosts add on a known name keeps these fields.

ssh_options takes only options that cannot run code or write files on this machine, each written as -o Keyword=value with one plain value: for example -p, -i, -l, -J, Port, User, HostName, HostKeyAlias, IdentityFile, StrictHostKeyChecking, the ServerAlive options and the algorithm lists. ProxyCommand, LocalCommand, the known hosts files, ControlPath, socket forwards, -F and the like are refused. -J and ProxyJump take host names only. addr and command may not start with a dash. A host with a refused entry is ignored, and tuios hosts and the Inbox name the reason. Put such options in ~/.ssh/config. protocol.md has the verb by verb table.

The daemon's links never ask for a password, a passphrase or a code. They run ssh with BatchMode=yes. A client that can ask you, such as tuios-gpui, signs in to a machine itself and keeps that connection open as an ssh master in the folder cm beside the daemon's socket. That folder is $XDG_RUNTIME_DIR/tuios/cm, /run/user/<uid>/tuios/cm when XDG_RUNTIME_DIR is not set, or /tmp/tuios-<uid>/cm when neither exists. When that folder and its parent exist, are not symbolic links, belong to you and only you can open them, each link and tuios hosts test run ssh with -o ControlMaster=no and -o ControlPath=<folder>/%C. The link then uses the master when one is open for that machine, and connects as usual when none is. A machine that needs a password or a second factor then works for as long as the master is open. No secret is stored.

A link connects as usual and does not use the folder in these cases:

  • Your ~/.ssh/config gives the host a ControlPath. 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. Set XDG_RUNTIME_DIR to a shorter folder.
  • tuios runs on Windows. Win32-OpenSSH has no ControlMaster.

A master connection can outlive the network under it, for example when a laptop sleeps. The link's ssh then waits on it, and the link's keepalives do not reach it. The link pings its host when it carried nothing for 15 seconds. When the host does not answer, the link ends, and the next dial runs ssh with -o ControlPath=none and opens a connection of its own. The link does the same after this machine wakes from sleep, and after a dial that timed out. A machine that needs a password or a second factor fails that one dial, and the dial after it uses the master again.

%C names a master by the local host, the remote host, the port and the user. It does not include a ProxyCommand, so a host reached through two different proxy commands shares one master. It includes the jump host only on OpenSSH 10.6 and later. On an earlier version, a host reached through two different jump hosts also shares one master.

tailscale_login is the origin of a Headscale server that sends the Tailscale SSH check for this host, for example "https://headscale.example". tuios shows and opens a sign-in link only on login.tailscale.com, controlplane.tailscale.com and this origin, over https, with the host matched exactly. Anything on the host can print the banner that carries the link. See Tailscale SSH check mode.

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