Install Natamux

Natamux is a desktop app for macOS (Apple silicon and Intel), Windows and Linux, all on 64-bit. The macOS and Linux apps update themselves; on Windows the app tells you about a new version and you run the new installer.

Requirements

• git. Natamux makes a git worktree for each task. On Windows, install Git for Windows.
• Windows only: Windows 10 version 1809 or later, or Windows 11, on x64. Windows on Arm may run the x64 app, but it is not tested.
• At least one coding agent, installed and logged in: claude, codex, gemini, copilot or cursor-agent. See Agents.
• gh (GitHub CLI), optional. Needed for opening pull requests, importing issues and CI status. Run gh auth login once.

Download

Get the file for your system from the latest release.

macOS, Apple siliconNatamux-mac-arm64.dmgmacOS, IntelNatamux-mac-x64.dmgWindows 10 and 11Natamux-win-x64.exeLinuxNatamux-linux-x86_64.AppImage

Every file:

System	File
macOS, Apple silicon (M1 and later)	Natamux-mac-arm64.dmg
macOS, Intel	Natamux-mac-x64.dmg
Windows 10 and 11, x64	Natamux-win-x64.exe
Linux, any distribution	Natamux-linux-x86_64.AppImage
Debian, Ubuntu	Natamux-linux-amd64.deb
Linux, no install	Natamux-linux-x64.tar.gz

Not sure which Mac you have? Open Apple menu → About This Mac. Chip: Apple M… means Apple silicon; Processor: Intel means Intel. You can also build the app from source with scripts/package-desktop.sh; see packages/desktop/README.md.

Install

Caution

The apps are not signed with an Apple or Windows certificate yet. Download them only from the Natamux releases page, and follow the first-open steps for your system below.

macOS

1. Open the .dmg and drag Natamux to Applications.

2. Open Natamux. macOS blocks it the first time.

3. Open System Settings → Privacy & Security and click Open Anyway.

4. If there is no such button, remove the quarantine flag and open the app again:

   xattr -dr com.apple.quarantine /Applications/Natamux.app

Windows

1. Run Natamux-win-x64.exe. Windows SmartScreen may show Windows protected your PC, because the installer is not signed.
2. Click More info, then Run anyway.
3. The installer needs no administrator rights. It installs Natamux for your user only, adds it to the Start menu and the desktop, and opens it.

Terminals of your tasks run PowerShell. A project’s setup script on Windows is .natamux-setup.ps1; see Workspaces. Install your agents so that PowerShell finds them: open a new PowerShell window and run claude --version (or codex, gemini, copilot, cursor-agent).

Linux

Pick one of three files.

AppImage

1. Make the file runnable, then start it:

   chmod +x Natamux-linux-x86_64.AppImage
   ./Natamux-linux-x86_64.AppImage

2. On Ubuntu 24.04 and later, the system can block Chromium’s sandbox, and the app does not start. Either install the .deb instead, or start the AppImage with --no-sandbox:

   ./Natamux-linux-x86_64.AppImage --no-sandbox

Debian and Ubuntu (.deb)

sudo apt install ./Natamux-linux-amd64.deb

The package installs the app as natamux-desktop, so the name natamux stays free for the command line.

tar.gz

Unpack Natamux-linux-x64.tar.gz anywhere and run the app from the folder. The same sandbox note as for the AppImage applies.

Docker

You need Docker with Compose, and a git repository. From a clone of the Natamux repository:

1. Set a token and the path of your repository:

   export NATAMUX_TOKEN="$(openssl rand -base64 32)"
   export NATAMUX_REPO=/path/to/the/git/repository

2. Start the two containers:

   docker compose -f compose.prod.yaml up -d --build

3. Open http://localhost:8080 and paste the token into the Daemon token field.

The images contain no coding agents. Docker keeps tasks, stages and the dashboard. To work with real agents, use the desktop app. See Self-host with Docker.

Verify the download

Download SHA256SUMS.txt and SHA256SUMS.txt.minisig from the same release and put them next to your file.

First check that the release key signed SHA256SUMS.txt, with minisign (brew install minisign, apt install minisign, or scoop install minisign):

minisign -Vm SHA256SUMS.txt -P RWSgtwsXHppEP5n4kgg1Q3yNIYODQNGsMQBKF93tjSRwzL1BrjeGoBpo

It must say Signature and comment signature verified and Trusted comment: natamux v… with the version you downloaded. Releases up to v0.1.23 have no signature.

Then check your file against SHA256SUMS.txt:

# macOS
shasum -a 256 -c SHA256SUMS.txt --ignore-missing

# Linux
sha256sum -c SHA256SUMS.txt --ignore-missing

On Windows, in PowerShell, compare the hash with the line for Natamux-win-x64.exe in SHA256SUMS.txt:

(Get-FileHash .\Natamux-win-x64.exe -Algorithm SHA256).Hash.ToLower()
Select-String Natamux-win-x64.exe .\SHA256SUMS.txt

On macOS and Linux you should see OK for the file you downloaded. On Windows the two hashes must be the same.

Run from source

For contributors. Natamux is developed in a GitHub Codespace, where Docker, Node.js and pnpm are ready. In the codespace terminal:

scripts/dev.sh demo

Open port 5173 and sign in with the token devtoken. The demo has a task with a workspace, commits and changes. scripts/dev.sh seed makes tasks in every state with fake agents at work. See docs/dev-setup.md and docs/docker.md in the repository.

To start the desktop app from the source tree, see packages/desktop/README.md.

Note

The development containers have no real coding agent. Use the desktop app to work with real agents.

Run with Docker

The production compose file runs the dashboard and the daemon in two hardened containers. It keeps tasks, stages and the dashboard, but its images contain no coding agents. See Self-host with Docker.

Use the natamux command in your own shell

The desktop app puts the natamux and nmx commands in its own terminals, so agents can run natamux done and natamux ask. To use them in your own shell, add the app’s bin folder to your PATH. The app rewrites the files in it each time it starts.

The folder is bin inside the app’s user data folder:

System	Folder
macOS	~/Library/Application Support/Natamux/bin
Windows	%APPDATA%\Natamux\bin
Linux	~/.config/Natamux/bin

macOS

Add one line to ~/.zshrc (zsh) or ~/.bashrc (bash):

~/.zshrc

export PATH="$HOME/Library/Application Support/Natamux/bin:$PATH"

Open a new shell. The command also needs the daemon’s token and address:

export NATAMUX_TOKEN="$(cat "$HOME/Library/Application Support/Natamux/daemon-token")"
export NATAMUX_URL=http://127.0.0.1:4317
natamux task list

Windows

In PowerShell, for your user, once:

[Environment]::SetEnvironmentVariable('Path', "$env:APPDATA\Natamux\bin;" + [Environment]::GetEnvironmentVariable('Path', 'User'), 'User')

Open a new shell. The command also needs the daemon’s token and address:

$env:NATAMUX_TOKEN = Get-Content "$env:APPDATA\Natamux\daemon-token"
$env:NATAMUX_URL = 'http://127.0.0.1:4317'
natamux task list

Linux

Add one line to ~/.zshrc (zsh) or ~/.bashrc (bash):

~/.bashrc

export PATH="$HOME/.config/Natamux/bin:$PATH"

Open a new shell. The command also needs the daemon’s token and address:

export NATAMUX_TOKEN="$(cat "$HOME/.config/Natamux/daemon-token")"
export NATAMUX_URL=http://127.0.0.1:4317
natamux task list

The app uses port 4317 when it is free, and another free port when it is not. Check the address in the dashboard’s browser URL or in the daemon log. See Desktop app and the CLI reference.

Next

Quick start.