SSH hosts

An SSH host is a machine you list once and connect to from the sidebar. Each pane on it opens your login shell there, so a dev box or a server sits beside your local workspaces. ZenTerm connects with the ssh that ships with macOS and reads the same ~/.ssh/config you already use.

Add a host

Open Settings with , and choose SSH Hosts, then Add Host…. Type a Host alias from ~/.ssh/config, or a user@host. Name is optional. A host can't contain spaces, commas, # or ", and it can't start with -.

Settings lists only the hosts you add. ZenTerm reads ~/.ssh/config to reach a host and never writes to it. Each row shows the host's address and its status. Click a row, or press Return on it, to change its name or remove it.

An added host gets a row in the sidebar's SSH section, under your workspaces. The section appears once you have a host. Settings writes each host to an ssh-host line in your config, and you can edit those lines by hand.

Name a host

A name is what ZenTerm shows in place of the alias: in the sidebar, on the Connect screen and in the window title. ssh still connects with the alias. Set or clear the name from the host's row in Settings, or write it after the alias in the config file:

Quote a name that holds #.

Online, Offline and Connected

A host is in one of three states. Settings shows the word, and the sidebar shows a dot.

• Offline is the quiet default. A host reads Offline until ZenTerm reaches it.
• Online means the host answered on its SSH port.
• Connected means you have a session open on it.

ZenTerm checks each host in the background every minute while the app is active, and again when the app comes forward, the Mac wakes or the network changes. The check asks the host's SSH port for its greeting and never logs in. A host that reaches you through ProxyJump or ProxyCommand reads Online once ZenTerm resolves its proxy, with no check of the host itself.

Connect

Click a host in the sidebar. A host that is not connected opens its Connect screen, which shows the route from your Mac to the host and its address. Press Return or Connect to open it. On an Offline host the screen asks "Connect anyway?", since the check can be wrong about a host behind a firewall or a proxy.

ZenTerm signs in with your ssh config, so keys, ProxyJump and the rest apply as they do in a shell. A password or passphrase prompt shows in the first pane, and the panes you open after it share that connection, so a host asks once.

A connected host opens in its own workspace, which lists under SSH and not under your workspaces. A host has one session across the app: choosing it from another window brings that session forward. If the login fails, ZenTerm posts a notice and returns to the Connect screen.

1 through 9 and [ and ] reach a connected host after your workspaces, in the order of the ssh-host lines. A host that is not connected is not in that order.

Disconnect

W on a host disconnects it. It does not ask first, even while the host is still connecting, and what is running in its panes ends. ZenTerm returns to the host's Connect screen. Closing the host's last pane, tab or workspace does the same, and never closes the window.

Removing a host in Settings disconnects it in every window. Settings asks first when the host is open.

What a pane on a host gets

Every pane, drawer and Scratch on a host opens your login shell there. Each one starts with TERM_PROGRAM and COLORTERM set as a local pane's are, so Claude reports its progress and programs use 24-bit color. TERM is xterm-256color. The host's last-login line and message of the day do not show.

A host whose ssh config sets RemoteCommand runs that command instead of a login shell. A host whose config ssh cannot read opens a plain ssh login.

Agents in a host's panes show in the sidebar's Agents list, and the host's dot takes the waiting color while one waits on you. An agent leaves the list when it exits.

What it does not get

Tool floats run on this Mac. A tool float you define does not open on a host, and ZenTerm says so in a notice. Scratch is the exception: it opens a shell on the host.

A host has no worktrees either. Worktrees belong to the workspaces on this Mac.