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
Section titled “What a remote host needs”- ssh access from your device. mocante runs your system’s
ssh, so everything in your~/.ssh/configapplies: host aliases, keys, your ssh agent,ProxyJumpandProxyCommand. Ifssh myhostworks in a terminal, mocante can usemyhost. - A login shell that runs
sh -c, such as bash, zsh or fish. mocante runs each command on the host assh -c '…'. A host whose login shell is nu cannot read this, so mocante does not support it. - 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
ghCLI, 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.
The copy is about 45 MB. Over a slow upload it can take several minutes. The host works over plain ssh until the copy is done, and then mocante switches to the helper by itself. If a copy fails, mocante tries again after a few minutes, then less often. Run Refresh hosts to try again at once.
Add a host
Section titled “Add a host”- Open the Hosts screen: click the drive icon (Hosts) at the top of the sidebar, or choose Hosts in the command palette.
- Click Add host. The palette command Add host… opens the same dialog.
- Enter a Name, which is how mocante shows the host, for example
build-vm. - Enter the Address: an alias from your
~/.ssh/config, oruser@host, with:portif it is not 22. - Optionally add Tags. Every session on this host carries them. See links and tags.
- Optionally add a Hostname: the name other devices reach this machine by, such as its Tailscale name. The web version opens the host’s
localhostpages there. - Optionally list the 1Password vaults that
opin this host’s sessions may read through your device. See 1Password on hosts. - Click Test connection. mocante connects and reports what it found, or why it failed. The test waits up to 12 seconds. If your ssh agent asks you first, such as a locked 1Password, approve it and click Test connection again: the second test joins the login that is waiting and does not start another. When mocante already has a connection to that address, the test runs over it, so it does not check a change you made to
~/.ssh/configsince. To check a changed config, runssh <address>in a terminal. - 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
Section titled “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 | mocante has not checked the host since it started, or its address changed. A host keeps its last state while mocante checks it again. |
| 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
Section titled “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:
- 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….
- A terminal dialog opens with a plain
sshto the host. Answer what it asks: accept a new host key, type a password, or unlock your ssh agent. - 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.
A host reports a different identity
Section titled “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. mocante then runs no commands there and opens no terminal or port forward to it, and it closes the terminals and forwards that are open. So an address that now points at a different machine never gets your commands, your keystrokes or your forwarded ssh agent. Log in over ssh… still works, so you can answer a changed host key.
When a host’s address changes, because you edited it or another of your devices did, mocante first checks the machine id at the new address. Until that check ends, which is usually a few seconds, the host runs no commands over ssh and opens no new terminal or port forward there, and those that need it fail with a message that the identity is being checked. Try again when the check is done.
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
Section titled “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
Section titled “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.
- Click Adopt… next to the session. The palette command Adopt session… lists all of them.
- Choose a Project, or type a new name to create one. mocante suggests the project whose workspace matches the session’s directory.
- 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
Section titled “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. When only the link to the mocante-agent helper drops, mocante connects it again at once and then with growing waits, over the ssh connection that is still open, so it does not ask your ssh agent for a new login. A connection that survived the sleep is kept, so its terminals carry on without a new login. Terminals reopen when the host is back, and tmux redraws the screen.
SSH agent forwarding
Section titled “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 opens two ssh connections per host: one that terminals, commit and push share, and one for its background work. Each logs in once, so your agent is asked once per connection and not for every terminal or command. mocante closes them ten minutes after the last use, and never joins a
ControlMasterconnection 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_sockon 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.