SSH projects

An SSH project is a canvas whose terminals run on a remote host instead of your own machine. You open it once, and from then on every terminal, editor and agent node on that canvas operates on the remote box — with the same persistence story you get locally.

What an SSH project is

Where a local project’s terminals are tmux sessions on your Mac, an SSH project’s terminals are tmux sessions on the remote host. The canvas, the nodes and the way you work with them are identical; only the machine underneath changes. Because the remote uses the same generated tmux config nodeterm uses locally, you get the same session continuity: sessions outlive the app, warm-reattach on reconnect, and cold-restore their scrollback if the remote reboots.

Connecting

You point a project at an endpoint — user@host — and nodeterm opens an SSH connection to it. All of the project’s traffic (terminals, git, file reads and writes) is multiplexed over a single shared connection (an SSH ControlMaster), so opening a dozen terminals doesn’t open a dozen SSH sessions.

The project file lives on the server, not on your laptop. A local project keeps its layout in <cwd>/.nodeterm/project.json; an SSH project keeps that same file on the remote host, so the canvas is tied to the machine the work is on. nodeterm holds an offline cache locally so a disconnected tab still renders, and reconciles the two on connect — the newer revision wins, and a populated canvas is never overwritten by an empty one. If you add the same folder twice, or open it from a second machine, nodeterm settles the conflict by content rather than blindly clobbering, so you don’t lose nodes or strand remote sessions.

Agents on the remote host

Agent nodes run the agent CLI on the remote host, exactly as a terminal does. Their status detection works over SSH too — the agent’s hooks are installed on the remote and report back, so you still get the pulsing RUNNING / NEEDS YOU badges, subagent cards and the context meter.

Two things resolve against the remote machine, not your local one:

• Permission mode. The auto permission mode needs a recent Claude Code, so nodeterm checks the remote host’s CLI version — that’s the CLI that actually runs the session. If the remote is too old or hasn’t been probed yet, auto is dropped for that project and the tab menu shows a ⚠︎ hint on the Auto rows.
• Claude accounts. Managed Claude accounts are per host. An SSH project only lists accounts whose host matches its connection (plus the System account); each remote account keeps its own config directory on the remote machine. Accounts for a host are added in Settings → Accounts while the project is connected.

Limits

Git worktrees are not supported on SSH projects in v1. The worktree affordances are shown disabled on an SSH project, with the reason, rather than hidden — a worktree binds to a checkout on a specific filesystem, and the safety checks that guard removal run against your local disk. Everything else on the canvas — terminals, agents, the editor, source control on the main checkout — works normally over the connection.