All pages

Docs · Right-sidebar surfaces

Connections

Availability: macOS · cloud workspace. The GTK app's Conn pane lists ~/.ssh/config hosts and opens ssh <host> in a tab — it does not read the saved-host store described here.

The Conn tab (right sidebar) is a connection drawer for SSH hosts, SFTP file browsers, port-forward presets, container shells, and multiplexer sessions. The goal: every machine and service you regularly touch is one click away, and the agent can drive them through tools without you typing the command.

SSH / Mosh hosts

Add a host (+ button) with:

  • Name — display label
  • User and Hostname (or alias)
  • Port — defaults to 22
  • Identity file — optional path to a private key
  • Use mosh — wraps the connection with mosh for flaky links
  • Connect on launch — open a tab and connect automatically each time TRMNLY starts
  • Extra ssh args — appended to the built command
  • Jump host chain — hop through one or more other saved hosts (-J)
  • Notes — free-form, shown under the row

Host keys are checked accept-new by default: the first connection pins the key, and a changed key refuses to connect rather than silently trusting it.

You can also import hosts from ~/.ssh/config — the Import wizard reads the file, lists each Host block, and lets you pick which ones to bring in.

Click a host to run the connection in the focused terminal pane. Status pills on the row reflect whether it's currently connected.

Expand a row (chevron) for the host's quick panel: one-switch toggles for the port-forward presets attached to it, an SFTP… button, and the host's remote tmux sessions (queried over ssh) with one-click attach.

SFTP browsers

The SFTP section (or the SFTP… button in a host's expanded row) opens a remote file browser: click into directories, download a file, or upload one with the Upload… button. Listings run ls over ssh; transfers shell out to sftp in batch mode — so auth must be passwordless (key or agent). Each operation is its own short-lived subprocess.

The agent has sftp_read and sftp_write tools that target a host by name or id — handy for "fetch this remote file and patch it locally." For shell-on-host work, use ssh_exec (and container_exec for container shells).

Port-forward presets

A preset is a named bundle of port-forward rules attached to one host. Rule types:

Type Flag Use
Local -L Expose a remote port on your machine
Remote -R Expose a local port to the remote machine
Dynamic SOCKS -D SOCKS proxy through the remote host

Toggle a preset on/off; TRMNLY runs the forwards in the background and shows their status in the Tunnels section. Presets that open a remote (-R) forward or bind a privileged port (below 1024) are marked as requiring confirmation — TRMNLY asks before opening the tunnel, and also warns when the host's GatewayPorts setting would expose the listener to the LAN.

A preset can also name the project its local listeners serve, which lets the Ports panel attribute the tunnel to that project.

The agent lists presets with port_forward_list and turns one on or off with port_forward_apply.

Containers

The Containers section has four sub-tabs — Containers, Images, Compose, and Ports (see Ports). Discovered runtimes:

  • Docker (Docker Desktop)
  • OrbStack
  • Colima
  • TRMNLY — the built-in engine (below)

Each running container shows up as a row. Click to open a shell into it (docker exec -it …, trying bash and falling back to sh). The agent has full Docker tooling (docker_compose_up, docker_container_logs, etc.) so you can ask it to restart a stack or tail logs.

Built-in engine

On macOS 26 with Apple silicon, TRMNLY can run containers itself — no Docker, OrbStack, or Colima installed. Images are pulled straight from the registry and each container boots as its own lightweight microVM. The guest Linux kernel is downloaded on first use (or adopted from an existing apple/container install to skip the download).

Trade-offs to know about:

  • Containers run inside the app — quitting TRMNLY stops them. Their filesystems persist on disk, so starting a stopped container resumes it with its writes intact.
  • Published ports (-p 8080:80) are relayed to localhost by TRMNLY.
  • There's no host-side CLI to attach a terminal to — ask the agent to run commands inside one with container_exec.
  • Compose isn't supported by the built-in engine.

Built-in containers appear in the same panel and answer to the same docker_* agent tools as the other runtimes.

Multiplexers

The panel lists your local tmux and screen sessions so you can reattach with one click rather than re-typing tmux attach -t <name>. Each session row offers two attach actions:

  • Attach — reattach in the focused pane.
  • Attach in a new split — reattach in a freshly spawned split, so the session joins the visible grid alongside what you're already running.

To start a fresh detachable session without typing the command, use View → New tmux Pane — it opens a new split running tmux new-session, giving you a pane you can detach from and reattach later.

The agent can drive a specific session with the run_in_pane tool (tmux send-keys under the hood). See Splits for grid layouts and broadcast input across the panes you attach.

What lives where

  • Hosts and presets: ~/Library/Application Support/TRMNLY/connections.json (encrypted)
  • SSH config parser: SSHConfigParser.swift
  • The agent uses AgentToolsConnections.swift to expose these via tools