Maestro for Linux

Why Linux developers use Maestro

Apps for running coding agents in parallel have mostly been Mac-only, including Conductor, whose site says it runs agents "on your Mac" (as of October 2026). Maestro runs natively on Linux and adds a few things on top:

• No workspace cap. Run as many parallel agents as your machine can handle. There is no limit on open workspaces.
• Every major agent CLI. Claude Code, Codex, Cursor, OpenCode, Kimi Code, and Grok Build, or a plain shell workspace. You pick the agent per workspace.
• True isolation. Each workspace is its own git worktree on its own branch, so agents never trample each other's changes. See how parallel Claude Code works with git worktrees.
• Review without leaving. Read the diff, edit files in the built-in editor (including Jupyter notebooks), preview web apps in the integrated browser, and open a PR from the app.
• Fast worktrees on btrfs and XFS. When a new worktree's lockfile matches a sibling's, Maestro gives it that sibling's node_modules as a copy-on-write clone (cp --reflink). The install takes seconds and uses almost no extra disk. On other filesystems, dependencies install normally.
• A memory guard. While an agent turn runs, Maestro watches RAM and swap. If a process that turn started is about to run the machine out, Maestro stops that one process before the kernel's OOM killer picks a victim on its own, and tells you why. It's on by default (Settings → Memory guard).
• Local folders and SSH remotes. Work in plain folders or on remote Linux and macOS machines over SSH, including hosts behind ProxyCommand / ProxyJump.

Install on Linux

AppImage requirements: FUSE

Maestro's AppImage uses the classic type-2 runtime, which mounts the app with FUSE 2 (libfuse.so.2). Many current distros ship only FUSE 3, so if double-clicking does nothing, or the terminal says AppImages require FUSE to run, install the FUSE 2 library:

# Ubuntu 24.04+ (the package was renamed)
sudo apt install libfuse2t64
# Ubuntu 22.04, Debian
sudo apt install libfuse2
# Fedora
sudo dnf install fuse fuse-libs
# Arch
sudo pacman -S fuse2
# openSUSE
sudo zypper install libfuse2

Don't remove fuse3 to do this. Both versions install side by side. If you can't install FUSE at all (in some containers, for example), run ./Maestro-*.AppImage --appimage-extract-and-run. It unpacks to a temporary folder on every launch, so it's slower.

Do I need --no-sandbox?

Usually not. Ubuntu 24.04 and later restrict unprivileged user namespaces through AppArmor, and that restriction makes many Electron AppImages crash with "The SUID sandbox helper binary was found, but is not configured correctly". Maestro's AppImage launcher checks for this before it starts the app (it tries unshare -Ur true). If user namespaces aren't available, it adds --no-sandbox itself. So Maestro starts either way, but on those systems Chromium's renderer sandbox is off. If you want it on, give user namespaces back, either with an AppArmor profile or system-wide (this lowers your system's protection, so read Ubuntu's explanation first):

sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

Add Maestro to your app launcher

The AppImage doesn't register itself with your desktop, so it won't appear in your launcher until you add an entry. Rename the file to Maestro.AppImage first. The updater keeps a file name that has no version number and overwrites it in place. With the versioned file name, each update saves the new version under its own versioned name and deletes the old file, which breaks any shortcut that points at it.

mkdir -p ~/Applications ~/.local/share/applications ~/.local/share/icons
mv ~/Downloads/Maestro-*.AppImage ~/Applications/Maestro.AppImage
chmod +x ~/Applications/Maestro.AppImage

# pull the icon out of the AppImage
ICON=usr/share/icons/hicolor/1024x1024/apps/maestro.png
cd /tmp && ~/Applications/Maestro.AppImage --appimage-extract "$ICON" \
  && mv "squashfs-root/$ICON" ~/.local/share/icons/maestro.png && rm -rf squashfs-root

cat > ~/.local/share/applications/maestro.desktop <<EOF
[Desktop Entry]
Name=Maestro
Comment=Run CLI coding agents in parallel, each in its own git worktree
Exec=$HOME/Applications/Maestro.AppImage %U
Icon=$HOME/.local/share/icons/maestro.png
Type=Application
Categories=Development;
StartupWMClass=Maestro
Terminal=false
EOF

StartupWMClass=Maestro matches the window class in Maestro's own bundled desktop entry, so docks group the window under this launcher. Tools like AppImageLauncher or Gear Lever can do the same job if you prefer a GUI.

Install the agent CLIs on Linux

These are the vendors' own commands as of October 2026 (sources at the end of this page):

# Claude Code (Anthropic's native installer; apt/dnf/apk repos also exist)
curl -fsSL https://claude.ai/install.sh | bash

# Codex (OpenAI)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Cursor agent CLI
curl https://cursor.com/install -fsS | bash

# OpenCode
curl -fsSL https://opencode.ai/install | bash

You can also install from inside Maestro. When a CLI isn't detected, Settings → Harnesses shows an Install button that runs the install command in a terminal inside the app: npm install -g … for Claude Code, Codex, OpenCode, and Kimi Code (so you need Node.js), and the vendor's curl script for Cursor and Grok Build.

Then sign in. Run the CLI once in a terminal, or use the Sign in button in Settings → Harnesses, which runs the CLI's own login inside the app. Maestro doesn't hold your credentials: each CLI keeps its own sign-in, and your Claude or ChatGPT plan pays for the usage as it does in the terminal. If you'd rather use an API key, save it in Settings and Maestro passes it to the CLI as an environment variable. More on each agent: Claude Code GUI, Codex GUI.

How Maestro finds your tools (PATH)

A launcher icon doesn't run your shell's startup files, so Maestro rebuilds your PATH itself at startup. It runs your login shell ($SHELL -lc env) and copies PATH, HOME, NVM_DIR, GOPATH, and SSH_AUTH_SOCK from it. It then appends ~/.local/bin, ~/bin, /usr/local/bin, and its own tools folder. That covers the default install locations of Claude Code and Cursor (~/.local/bin).

The catch: a login shell reads ~/.profile or ~/.bash_profile (bash) and ~/.zprofile or ~/.zshenv (zsh), but not the interactive-only parts of ~/.bashrc or ~/.zshrc. Ubuntu's default ~/.bashrc returns early for non-interactive shells, so PATH lines that installers append at its end (nvm, for example) never reach Maestro. If a CLI works in your terminal but Maestro says it isn't installed, move that PATH line into ~/.profile (bash) or ~/.zprofile (zsh), then restart Maestro.

Updates

Run as an AppImage, Maestro updates itself. It checks at launch, every two minutes while running, and when you focus the window or wake the machine. It downloads the update in the background, using a block map to fetch only the changed parts when it can, then shows Restart to update. If you just quit, the update installs on quit. Updates only work when you launch the .AppImage file itself, and the file and its folder must be writable by your user. Don't put it in a root-owned /opt.

Troubleshooting

Nothing happens when I run the AppImage

Run it from a terminal to see the error. AppImages require FUSE means installing libfuse2. Permission denied means it needs chmod +x, or the file is on a partition mounted noexec.

An agent shows "Not installed" but works in my terminal

It's almost always the PATH note above. Check with bash -lc 'command -v claude' (use your own shell and CLI name). If that prints nothing, Maestro can't see the CLI either. Maestro also caches what it detected for a few minutes, so restart it after fixing PATH.

GitHub sign-in fails

Install the GitHub CLI (gh) from your distro or GitHub's packages. On macOS and Windows Maestro can download gh for you, but that automatic download doesn't cover Linux yet (as of October 2026).

"Open in terminal" does nothing

On Linux it runs x-terminal-emulator, which Debian and Ubuntu provide but many other distros don't. Each workspace's built-in terminal works regardless.

The Preview tab doesn't list servers already running on my machine

That list comes from lsof. Install it (sudo apt install lsof or your distro's equivalent).

Maestro is slow on integrated graphics

Settings → Visual effects → Reduced swaps the glass and blur effects for solid surfaces.

Distros and known limitations

Being honest about the rough edges, as of October 2026:

• The AppImage is built on GitHub's Ubuntu runner and should run on any current x86_64 glibc desktop distro, such as Ubuntu, Debian, Fedora, Arch, or openSUSE. We don't run a per-distro test matrix, though. If it breaks on yours, open an issue.
• x86_64 only. There's no ARM64 build, and there are no .deb, .rpm, Flatpak, or Snap packages.
• The AppImage isn't signed. Each release lists a base64 SHA-512 checksum in the update feed. Compare it with openssl dgst -sha512 -binary Maestro-*.AppImage | base64 -w0.
• Voice dictation is macOS-only.

To uninstall, delete the AppImage and your .desktop file. Settings and the database live in ~/.config/Maestro, and worktrees live in ~/maestro. Check those for uncommitted work, delete them, and run git worktree prune in your repos.

Sources (checked October 2026)

• docs.appimage.org: FUSE troubleshooting and the AppImageKit FUSE wiki: libfuse2 packages per distro, --appimage-extract-and-run
• ubuntu.com: restricted unprivileged user namespaces and the Ubuntu 24.04 release notes
• code.claude.com/docs/en/setup: Claude Code install, Linux package repos
• code.claude.com/docs/en/desktop-linux: Claude desktop app on Linux (beta)
• github.com/openai/codex: Codex CLI install
• cursor.com/docs/cli/installation: Cursor agent CLI install
• opencode.ai/docs: OpenCode install
• conductor.build: Conductor platform

Maestro is an independent project, not affiliated with Conductor / Melty Labs, Anthropic, OpenAI, or Cursor. Vendor details come from their public docs as of October 12, 2026; agent CLIs change quickly, so check the linked pages if a command fails.