Guide

Getting started

Mudskipper has two parts: the desktop app, and gw, a gateway that runs on each machine, starts the coding agents there and keeps their chats. Closing the app does not stop a running turn; the gateway runs as a background service (launchd on macOS, a systemd user unit on Linux).

Install

Get the installer for your system from Download.

• macOS: .dmg, Apple silicon or Intel.
• Linux: AppImage, .deb or .rpm, x64 or arm64.
• Windows: .exe or .msi, x64. The gateway does not run on Windows itself; the app runs it inside your WSL Linux distro, so WSL must be installed.

For hosted macOS compute, see Cloud Mac setup, billing and recovery help.

First launch

On first launch the app opens Setup at Where should your agents run? and starts a gateway on this computer; on Windows, the first setup downloads it into WSL.

1. Choose Use this machine.
2. Under Agents on your machine, install the agents you want and sign in to them (next section).
3. Press Finish setup, or Set up another machine to add a second one first.

If the local gateway does not answer, Setup shows the command to install it as a service by hand: gw service install. To run Setup again later, open the machine's menu in Options → Machines and choose Run setup again.

Agents

Supported: Claude Code, Codex, OpenCode, Cursor CLI, Kimi Code CLI, Qwen Code, Auggie and Claude Code (ACP). Each agent is the vendor's own CLI, installed on the machine that runs its chats and signed in to your account with that vendor. Which controls a chat shows depends on what the agent reports.

Options → Agents lists every agent on every machine. A missing agent has Install; an installed one that needs credentials has Sign in, which, depending on the agent, stores a pasted key on the machine, starts a device sign-in and shows its code, or gives the command to run on the machine. Install and sign-in run on the machine and show their command while they work. An installed agent's menu has Uninstall…, and Sign out… while it is signed in.

Chats

New chat (⌘N) has three fields above the message box:

• Machine: where the agent runs.
• Folder: a path on that machine. Type it, pick a project, or browse with the folder button.
• Agent: ⌘< and ⌘> step through the machine's agents.

For a git folder, choose This folder to work on its current branch, or New worktree to work on a branch of its own. The model menu in the message box sets the model and, where the agent has it, the effort level; the choice applies when the chat starts. Write the task and press Start.

In an open chat, the agent name in the header switches the chat to another agent on the same machine, which is given the conversation so far.

Approvals and changes

The access menu in the message box has two modes:

• Ask for approval: asks before actions your agent does not already allow.
• Full access: approves every action without asking.

A request shows the command, file diff or tool call with Allow once, Allow always (for the rest of the chat) and Deny. Agents that support saved rules add a button per suggested rule.

Changes in the chat's side panel lists the changed files of each checkout the chat works in, against its base branch. Click a file for its diff. The revert button on a row reverts that file to the base branch, after a confirmation. Review with… asks another installed agent to review the branch, read-only.

Another machine

A Linux or macOS machine can run chats too. Add it in Options → Machines → Add a machine, one of three ways:

• Install over SSH: enter an SSH alias (any host in ~/.ssh/config, or user@host) and press Install and connect. The app installs gw there and runs it as a service. SSH must work without a prompt; for a new host, run ssh <host> once by hand to accept its host key. Not offered in the Windows app.
• Account: install gw on the machine (command on Download), run gw login there, and approve the code it prints, either at the link it shows or in this form. Machines linked to your account then appear in the list on every device signed in to it.
• Pairing string: run gw p2p --enable on the machine and paste the string from its last line.

The app reaches other machines through the Mudskipper relay. That needs this app signed in (Options → Account → Sign in, which opens the browser with a code to confirm) to an account with Mudskipper Pro. No public IP or open port is needed on the machine. This computer needs no account.

Updates

The app checks for updates at launch and every six hours, and downloads them in the background. Update ready then appears at the top of the window; press Restart to update, or Later.

The app updates this computer's gateway when it starts. A connected machine whose gw is older than the app's is updated once its running turns finish; when a machine needs it, its card in Options → Machines shows Update gateway to do it at once.

Shortcuts

⌘K searches chats, ⌘, opens Options, and ⌘/ lists every shortcut. On Windows and Linux, ⌘ is Ctrl.

Support

Email support@deskmint.ai.