Remote access

You can use Splinterm on another machine over SSH in two ways:

• Open a remote Dojo in a native window on your desktop.
• Connect an automation tool through an SSH relay, with its own permissions.

Neither requires opening a network port on splinterd. SSH authenticates your login for graphical use, but it does not grant tool permissions. Automation still needs a policy for the exact program making the requests.

Configure a remote profile

Profiles live at ${XDG_CONFIG_HOME:-~/.config}/splinterm/remotes.toml:

version = 1

[remotes.wintermute]
host = "wintermute"
user = "operator"
port = 22
identity_files = ["~/.ssh/id_ed25519"]
known_hosts_file = "~/.ssh/known_hosts"
connect_timeout_seconds = 15

The schema is strict. It does not accept arbitrary SSH options, commands, forwarding, environment, or shell fragments. Ordinary safe aliases, identities, certificates, agents, and proxy routing may still come from OpenSSH configuration; Splinterm supplies fixed safety overrides.

Inspect and probe without opening a Window:

splinterm remote list
splinterm remote inspect wintermute
splinterm remote check wintermute

remote inspect prints resolved non-secret settings and structured SSH argv. remote check performs bounded SSH, relay, daemon, Ping, and ListLairs probes without mutating topology.

Open a native remote Window

splinterm --remote wintermute
splinterm --remote wintermute dojos
splinterm --remote wintermute reopen
splinterm --remote wintermute launch --working-directory /srv/project
splinterm --remote wintermute window --lair-id LAIR_ID --dojo-id DOJO_ID

Omitting the command opens the remote Recent Dojos picker. A Window stays bound to one endpoint and can discover, attach, split, control, search, and restore remote Dojos through one OpenSSH child. New remote panes briefly show a client-local Opening remote pane… placeholder while bounded protocol round trips complete.

OpenSSH may use the controlling terminal for passwords, key passphrases, PINs, or hardware tokens. Unknown or changed host keys fail closed. Splinterm does not run ssh-keyscan, accept unknown keys, or store credentials.

Authority and boundaries

A native remote Window receives ordinary human multiplexer authority after SSH authenticates the remote account. It can request normal controller ownership but cannot use trusted-local forced takeover. It also does not publish local compositor focus or receive remote terminal image bodies.

SSH or relay loss closes the affected local views and releases connection-owned controllers. It sends no kill or close request, so daemon-owned remote Splints continue running.

Remote images

Remote graphical sessions intentionally omit terminal image transfer. Unexpected remote image metadata fails the affected pane closed rather than opening a content channel.

Automation over SSH

The machine relay is a different entry point:

ssh -T \
  -o StrictHostKeyChecking=yes \
  ACCOUNT@HOST \
  /usr/bin/splinterm relay --stdio

It copies bounded private-protocol bytes over stdio. The remote daemon authorizes the exact installed splinterm-relay executable under an owner-controlled policy. SSH login, socket access, and Unix account identity do not grant machine operations.

Use a dedicated account or restricted key when relay callers must not inherit the account’s other SSH capabilities. Relay stdout is protocol data only; diagnostics stay on stderr.

For the complete relay identity, profile schema, authentication, reconnect, and policy contract, read repository docs/remote.md.