Remote hosts

A remote host is any machine you can reach with ssh: a VM, a build server, a desktop in another room. Once you add it, you run agents there the same way as on your own machine, and their sessions keep running when you close the laptop.

What a remote host needs

• ssh access from your device. mocante runs your system’s ssh, so everything in your ~/.ssh/config applies: host aliases, keys, your ssh agent, ProxyJump and ProxyCommand. If ssh myhost works in a terminal, mocante can use myhost.
• tmux. Every session is a tmux session on the host. A host without tmux fails its check, and the Hosts screen says so.
• git, for git workspaces and worktree sessions.
• Optionally the gh CLI, for pull request suggestions.

You do not install mocante on the host. When your device first connects, it copies a small helper program, mocante-agent, to ~/.local/share/mocante/ on the host over ssh, and updates it when mocante updates. The helper opens no network port. It exists for Linux (x64 and arm64) and macOS (Intel and Apple Silicon).

On other platforms mocante still works over plain ssh, with fewer features: session status updates more slowly, and the host shows no resource meters.

Add a host

1. Open the Hosts screen: click the drive icon (Hosts) at the top of the sidebar, or choose Hosts in the command palette.
2. Click Add host. The palette command Add host… opens the same dialog.
3. Enter a Name, which is how mocante shows the host, for example build-vm.
4. Enter the Address: an alias from your ~/.ssh/config, or user@host, with :port if it is not 22.
5. Optionally add Tags. Every session on this host carries them. See links and tags.
6. Click Test connection. mocante connects and reports what it found, or why it failed.
7. Click Add host.

To change a host later, click the pencil on its row, or right-click the row and choose Edit host…. Remove host is at the bottom of the edit dialog. You cannot remove your own machine.

Read the Hosts screen

Each host has a row with a status dot, its name, its address, its state and when it was last seen. A connected host also shows its CPU, memory and disk use under the row.

State	Meaning
connected	mocante reaches the host and sees its sessions.
connecting	A check is in progress.
unreachable	The host did not answer. The error from ssh shows under the row.
needs you	The host’s ssh server answers, but something needs a person: a changed host key, a key the host refuses, a locked ssh agent, a password prompt, or a missing tmux.

The refresh button at the top (Re-check connections and sessions) checks every host again. Right-click a host row for Edit host…, Log in over ssh…, Re-check connection and Copy address.

Fix a host that needs you

When a host shows needs you, the row shows everything ssh printed. mocante does not guess at the cause. Instead, it lets you answer ssh yourself:

1. Click Log in over ssh… on the host row. The same command is in the host’s right-click menu, and in the palette as Log in to a host over ssh….
2. A terminal dialog opens with a plain ssh to the host. Answer what it asks: accept a new host key, type a password, or unlock your ssh agent.
3. Close the dialog when you are logged in. mocante checks the host again.

This login does not forward your ssh agent, ports or X11, because the host may not be the machine it was before.

mocante also checks a needs you host again every minute, so a problem that fixes itself, such as a password manager that you unlock, clears on its own.

Note

A host behind ProxyJump or ProxyCommand always shows unreachable when it fails, because mocante cannot reach its ssh server directly to tell the two cases apart. Log in over ssh… still works from its right-click menu.

A host reports a different identity

Each host has a machine id, which mocante records the first time it connects. If a host later reports a different id, or a new address claims the id of another known host, the row says so and mocante stops running commands through it. This protects you from an address that now points at a different machine.

If you know why, for example you reinstalled the machine, click Trust new identity on the row (in the palette: Trust a host’s new identity…) and confirm.

Agent hooks are out of date

When a host has agent hooks from an older mocante, the row says so. Click Update hooks, then restart the agent.

Adopt existing tmux sessions

tmux sessions that mocante did not create show under their host as Unmanaged sessions found, with their window count and directory.

1. Click Adopt… next to the session. The palette command Adopt session… lists all of them.
2. Choose a Project, or type a new name to create one. mocante suggests the project whose workspace matches the session’s directory.
3. Keep or change the session’s name, and confirm.

The session keeps running as it was. It now appears in the sidebar and the fleet like any other.

When a host goes offline

Sessions run in tmux on the host, so they keep running when your device loses the connection, sleeps or quits. While a host is unreachable, its sessions show host offline.

mocante reconnects by itself. After your device wakes from sleep or changes networks, it checks every host at once and keeps retrying every few seconds while a host stays unreachable. Terminals reopen when the host is back, and tmux redraws the screen.

SSH agent forwarding

If your ~/.ssh/config forwards an ssh agent to a host (ForwardAgent yes), for example a 1Password agent that signs your git commits:

• Terminals, commit and push follow your ssh config, so the agent is available in your tmux panes and to commits, as in a manual ssh session.
• mocante’s background connections (status checks, tmux queries) never forward your agent, ports or X11, whatever your config says.
• mocante shares one ssh connection per host between its terminals and git commands, and closes it ten minutes after the last use. It never joins a ControlMaster connection of your own.
• A forwarded agent gets a new socket on every login, which normally breaks older shells after a reconnect. mocante points ~/.ssh/ssh_auth_sock on the host at the newest socket and gives tmux panes that path, so every pane reaches the current agent. With two devices attached, panes use the agent of the device that attached last.

A locked ssh agent

ssh waits without a time limit for an agent that does not answer, such as a locked 1Password. mocante stops a remote terminal that shows no output for 30 seconds and tries again. If a host stays stuck, unlock your agent, or use Log in over ssh… on its row.