Installation

mocante ships as a desktop app for macOS on Apple Silicon and for Linux on x64. This page tells you what to download, which tools each machine needs, and what you see when you launch the app.

Download

Get the newest release from the releases page on GitHub. Releases marked Latest are stable. Releases marked Pre-release are beta or test builds.

Platform	File
macOS, Apple Silicon	mocante-<version>-arm64.dmg
Linux x64, any distro	mocante-<version>.AppImage
Linux x64, Debian/Ubuntu	mocante_<version>_amd64.deb

Ignore the .zip, .blockmap and .yml files. The app uses them to update itself.

There is no build for Intel Macs, Windows or Linux on ARM. On those machines you can run the web UI from source.

Install the app

macOS

1. Download mocante-<version>-arm64.dmg.

2. Open the dmg and drag mocante to Applications.

3. Open mocante from Applications. The app is signed and notarized, so macOS opens it without a security warning.

4. Allow notifications when macOS asks. mocante uses them to tell you when an agent needs you.

Linux

Use the deb on Debian, Ubuntu and their derivatives. Use the AppImage anywhere else.

deb

sudo apt install ./mocante_<version>_amd64.deb

AppImage

chmod +x mocante-<version>.AppImage
./mocante-<version>.AppImage

Keep the AppImage where you put it. The app updates the file in place.

Install the tools mocante needs

mocante runs your sessions in tmux and reads your repositories with git. It does not install these for you.

On the machine that runs the app

• tmux. Your own machine is a host too, and every host needs tmux.
• git, for git workspaces, worktrees and the git panel.
• ssh, the OpenSSH client, if you want to use remote hosts. mocante uses the system ssh and your ~/.ssh/config.
• gh, the GitHub CLI, optional. Sign in with gh auth login. mocante uses it to suggest open pull requests and issues when you start a session, and to open pull requests.

macOS

brew install tmux git gh

Linux

sudo apt install tmux git openssh-client

Install gh from the GitHub CLI instructions if you want it.

On each remote host

• tmux and git.
• curl, if you want agent hooks for exact agent status.
• The agents you want to run, such as claude or codex.

A remote host can run Linux or macOS on x64 or ARM. mocante copies a small helper program to ~/.local/share/mocante/ on the host the first time it connects, over the same SSH connection. You do not install anything else. See remote hosts.

First launch

On first launch, mocante opens with an empty sidebar. Your own machine is already a host, so you can start work at once:

• Click New project in the sidebar to create your first project. Your first session walks you through it.
• Click the Hosts button (the drive icon) at the top of the sidebar to add a remote host or to adopt tmux sessions that already run.

If a host shows a problem, such as tmux missing, the Hosts page tells you why. See troubleshooting.

Updating

The app checks for updates itself and asks before it downloads one. See updates for how updates install and how to switch between the stable and beta channels.

Run from source

Note

This is for advanced users and contributors. The desktop app is the easiest way to use mocante.

You can run mocante as a web UI in your browser from a clone of the repository. You need Node and pnpm at the versions pinned in the repository’s mise.toml, plus tmux and git.

git clone https://github.com/uplift-ltd/mocante.git
cd mocante
pnpm install
pnpm dev

Then open http://localhost:4123. The web UI listens on localhost only by default, and it does not update itself: pull and restart to update. See the repository’s README and development notes for details, and security before you open it to the network.