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.

Hosts

A host says tmux is missing

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.

A remote host shows “needs you”

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.

A remote host shows “unreachable”

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

This usually means your SSH agent is locked, for example 1Password. SSH waits for the agent to unlock and has no timeout of its own.

Unlock your SSH agent. mocante checks hosts that need you every minute, and a terminal that shows no output for 30 seconds reconnects on its own, so the host comes back soon after you unlock. To force it, use Log in over ssh… on the host.

Terminals freeze after my laptop sleeps

mocante notices when the machine wakes up, reconnects remote terminals over a fresh SSH connection, and checks every host again. A dead connection is dropped within about 45 seconds. Your sessions keep running in tmux on the host the whole time, so nothing is lost; the terminal redraws when it reconnects.

If a terminal still does not come back, focus the window, or switch to another tab and back.

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.

Agents

An agent is not detected

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.

The status is wrong or lags

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. 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.

Installing hooks fails

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.

Notifications

I get no notifications

• 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.

Notifications have no Approve button

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.

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

Updates

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.

“Update check failed”

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 went back to Stable

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 Linux update asks for a password

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.

Still stuck

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.