Skip to content

Troubleshooting

This page lists problems you may run into and what to do about each. Most host problems show their cause on the Hosts page, so start there: click the Hosts button (the drive icon) at the top of the sidebar.

Every host needs tmux, including your own machine. The Hosts page shows why a host failed its check, for example that tmux is missing.

Install tmux on that host, for example with brew install tmux on macOS or sudo apt install tmux on Debian and Ubuntu. mocante checks the host again on its own; on a remote host that shows needs you, you can also click Log in over ssh… and close the dialog to check at once.

The host’s SSH server answers, but SSH needs something from you. Common causes are a changed host key, a key the host refuses, a locked SSH agent, or a missing tmux. The Hosts page shows the full SSH output.

  1. Click Log in over ssh… on the host row. It is also in the host’s right-click menu and in the command palette as Log in to a host over ssh….
  2. Answer SSH in the dialog: accept the new host key, type a password, or unlock your key.
  3. Close the dialog. mocante checks the host again as soon as the SSH session ends.

mocante could not reach the host’s SSH server. Check that:

  • the host is running and on the network, and any VPN you need is connected,
  • the address in the host’s settings works with plain ssh in a terminal,
  • your ~/.ssh/config has the right HostName, Port, User and key for it.

mocante uses the system ssh and your ~/.ssh/config, so if ssh <address> works in your terminal, it works in mocante.

A host that you reach through ProxyJump or ProxyCommand always shows unreachable when it fails, even when the real cause is a host key or a locked key, because mocante cannot reach its SSH server directly. Run ssh <address> in a terminal to see what it wants.

While a remote host is unreachable, mocante tries again every five seconds.

A host hangs while it connects, or terminals stay blank

Section titled “A host hangs while it connects, or terminals stay blank”

This usually means your SSH agent is waiting for you, for example a locked 1Password. Approve its prompt.

mocante logs in to each host once, not once for each terminal, and that login waits up to 90 seconds for your agent. The host and its terminals come back as soon as you approve. If you miss the prompt, the host shows ssh did not log in within 90 seconds, and mocante asks again when a terminal reconnects, at the next check a minute later, or when you use Log in over ssh… on the host.

mocante notices when the machine wakes up and checks each SSH connection. A connection that still works is kept, so its terminals pick up where they were, with no new login and no prompt from your SSH agent. Wi-Fi can take a while to come back after a wake, so mocante gives a connection up to 75 seconds to answer before it treats it as dead. A dead connection is replaced, which takes one login per host that your agent may ask you to approve. Your sessions keep running in tmux on the host the whole time, so nothing is lost; the terminal redraws when it reconnects.

If a login was still waiting for your SSH agent when the machine went to sleep, and it started more than two minutes before the wake, the host has already given up on it. mocante stops that login when the machine wakes and starts a new one, so the prompt that your agent shows is for a login that can still work.

When a connection is replaced, its terminals reconnect by themselves as soon as the new one is up. If a terminal still does not come back, switch to another session and back, which attaches it again.

If you reach the host through ProxyJump, ssh opens the connection to the jump host with your own ~/.ssh/config, including your own ControlMaster. A master of yours to the jump host that went stale during the sleep blocks the host. Stop it with ssh -O exit <jump host>.

The host refuses every connection for some minutes

Section titled “The host refuses every connection for some minutes”

OpenSSH 9.8 and later penalise an address that fails to log in many times, and then refuse every connection from it for up to ten minutes, your own ssh included. A locked SSH agent can cause this. On the host, journalctl -u ssh shows drop connection … penalty. Wait for the penalty to end. On a host that only trusted machines reach, PerSourcePenaltyExemptList in its sshd_config exempts your network.

A session I started outside mocante does not show

Section titled “A session I started outside mocante does not show”

tmux sessions that mocante did not create show on the Hosts page under their host. Click Adopt… next to one, or run Adopt session… from the command palette, to add it to a project.

tmux on the host already runs a session with the name mocante gives that branch or name, so mocante does not start a second one. Click Open existing on the message to open that session. If mocante did not know about it, it adds the session to the workspace first. Two branch names that differ only in characters mocante replaces with -, such as feat/x and feat-x, get the same session name. If that session runs the other branch, Open existing says so and does not open it.

mocante recognizes Claude Code, Codex, opencode and pi from the process that runs in the tab and from what the agent draws on screen. If a tab stays a plain shell:

  • Wait a moment. Detection runs on a regular scan, not instantly.
  • Make sure you started the agent in a tab of a mocante session, not in a separate terminal.
  • Install hooks for the agent: run Install agent hooks… from the command palette, pick the agent and the host, and then restart the agent. With hooks, the agent reports its own status.

Without hooks, mocante reads the screen, and a redrawn or reworded prompt can make it guess wrong. Install hooks as above for exact status.

If you see “Agent hooks on … are from an older mocante” in the fleet view, click View hosts, then click Update hooks on the host. To update all hosts at once, click Update agents at the top of the Hosts page. Restart the agents on that host afterwards. An agent reads its hooks only when it starts, so an agent that ran through an update keeps the old ones until you restart it.

The install stops without changing anything and tells you why. Common reasons:

  • For Claude Code, claude is not on the PATH on that host, or one of its plugin commands failed. The error ends with the commands to run by hand.
  • A file mocante would write already exists and mocante did not write it.
  • The agent’s JSON config file is not valid JSON.

Fix the cause and run Install agent hooks… again. To remove hooks, run Uninstall agent hooks…. mocante then falls back to reading the screen.

Hooks send their reports with curl. If a host has no curl, install it.

  • mocante does not notify you about a tab that is already on screen in a focused window.
  • On macOS, check that notifications for mocante are allowed in System Settings › Notifications.
  • In the web UI, allow notifications when the browser asks, or in the site settings of the browser.
  • Claude Code does not ring the terminal bell inside mocante on its own. To get a bell notification from it, set its notification channel to terminal_bell in its /config. With hooks installed, mocante notifies you when it needs input anyway.

To hear a tone with each notification, turn on Notification sound in Settings › Notifications.

The Approve button, with Deny behind it, shows only when:

  • the agent is Claude Code or Codex, with hooks installed,
  • the agent asks to run a tool, and the tab is not on screen,
  • you run the desktop app. On macOS this needs the signed release build.

opencode and pi notifications open the tab when you click them, but cannot approve. “Don’t ask again” is only offered in the agent’s own prompt in the terminal.

A request from an agent tool, such as starting a session, offers Allow once, Allow for this session and Deny instead, for every agent.

If nobody answers a request, it goes back to the agent after a few minutes, and the agent shows its own prompt.

Some actions take minutes when everything is fine: cloning a big repository, removing a workspace with its files, a push whose hooks run tests, or any action on a host that waits while you approve its SSH login, for example in 1Password. After a few seconds mocante shows Still working, and the toast closes when the action ends. Approve any prompt that waits for you.

An action that changes something got no answer before its time limit, which is minutes for most actions and longer for clones, pushes and removals. It may have finished anyway, so mocante does not try it again for you. Look at the result first, for example whether the workspace or the branch is there, then do the action again if it is needed.

A read that gets no answer in time says that nothing changed, and you can try it again at once.

Closing the workspace dialog while it clones cancels the action.

Once you confirm a removal, Cancel and Escape are disabled while it runs. The removal continues if its session or workspace disappears from the app before it finishes. If the action fails, the dialog shows the error and enables its controls again. If its session or workspace has already disappeared, a notification shows the error instead.

Settings says “Updates need the packaged desktop app”

Section titled “Settings says “Updates need the packaged desktop app””

You run mocante from source or from an unpacked build. Only the installed desktop app updates itself. Pull the repository and restart instead.

The status row in Settings › Updates shows the reason. Check your network connection and click Check now to try again. If it keeps failing, download the newest release from the releases page and install it over the old one. See installation.

A branch build follows Stable when its branch has no builds, for example after the branch is merged. Settings › Updates says so. This is expected; see updates.

The deb package installs with dpkg when the app quits, which needs your password. Type it to finish the update. The AppImage updates without a password, as long as you can write to the file.

Report the problem on GitHub issues. Say which version you run (Settings › Updates shows it), your platform, and what the Hosts page says about the host involved.