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 limithandshake_timeout: The server closes a connection that does not log in within this time. It is the same asLoginGraceTimein 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:
| Capability | What it lets the other machine do here |
|---|---|
list | Read: 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). |
mail | Send and read agent mail, and use the stash. |
open | Start processes: sessions, windows, worktrees, fans, start-agent, clones of a repository by its URL, and panes this machine runs for it. |
write | Change 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. |
respond | Answer 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. |
transcripts | Read 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. |
files | Read 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 = 50000A 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
filescan write any file inside its roots and read any file outside the deny list (or insidefiles_read_roots). A file copy is a way to run code: a binary dropped on yourPATH, a config a program reads. Givefiles, and a widefiles_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/configgives the host aControlPath. 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_DIRto 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.
Agents
Agents: part of the Configuration of TUIOS.
The appearance tables
The appearance tables: 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.