Install on your computer
Download the desktop app for Mac, Windows or Linux. The first launch sets this computer up to run your agents.
The desktop app is where you work with your agents, and it can also run them on this computer. Want supermux on a machine without a screen instead? See Install on a server.
Download
| Platform | Download |
|---|---|
| macOS (Apple silicon) | supermux-desktop-macos.dmg |
| Windows (x64) | supermux-windows.msi |
| Linux (x64) | supermux-linux.deb |
| iPhone, iPad | App Store |
| Android | supermux-android.apk |
The phone apps come in when you pair your devices.
Install the app
Open the .dmg and drag Supermux Desktop into Applications, then open it.
The Mac app needs Apple silicon. macOS asks for the microphone the first time you dictate, and may ask for local network access, which the app uses to reach your computers and devices.
The first launch
Let it set up this computer
You'll see Setting up this computer as a host…. A host is a computer that runs your agents. Here, that's this one.
Keep the QR code for your phone
When it's ready, the app says This computer is ready to host your agents. Scan the QR with your phone. Leave it open if you want to pair your phone now.
Choose whether it keeps running
Keep running in the background is on by default. Your agents stay reachable after you quit the app, sign out or restart.
Click Done
The sidebar opens with a Start a new session card. Next: your first session.
Below the QR code, the app tells you how your phone will reach this computer. Remote access is on through relay.supermux.dev means it works from anywhere, not just at home. See Reach your computer from anywhere.
Already run supermux on a server?
Click Connect to a different broker instead and paste a pairing link from that server. This computer then only shows your sessions; it doesn't run agents itself.
Git is optional
Agents work without git. Git adds worktrees, diffs and change tracking.
If git is missing, the first launch offers to install it: Install Apple's developer tools — optional on a Mac, or Install git — optional on Windows. You can also skip it and use Install… on the banner later.
On Linux, install git with your package manager, for example sudo apt install git.
Closing and quitting
Closing the window keeps supermux running in the menu bar or system tray, so your sessions carry on. To stop it, choose Quit supermux from that menu. On a Linux desktop without a system tray, closing the window quits instead.
If Keep running in the background is off, quitting asks first, because it stops your running sessions.
You can change all of this later in Settings ▸ Hosting. See Desktop app.
Introduction
supermux runs Claude Code, Codex, and other coding agents on your own computer or server, many sessions at once, and lets you work with them from your desktop or phone.
Install on a server
Run supermux on an always-on Linux box or Mac with one command, then work with it from your desktop or phone.