Docs/Get started

Install Moonfold

Moonfold runs coding agents on your computer and lets you control them from its desktop app or a web browser. Set up the machine where the agents will work first.

Requirements

You need an installed, authenticated provider before starting a thread. You can launch Moonfold and configure providers afterwards.

Command line

curl -fsSL https://raw.githubusercontent.com/Mr-Dark-debug/Moonfold/main/scripts/install.sh | sh

On Windows, in PowerShell:

irm https://raw.githubusercontent.com/Mr-Dark-debug/Moonfold/main/scripts/install.ps1 | iex

This installs the moonfold binary to ~/.local/bin. If your shell reports command not found afterwards, that directory is not on your PATH yet; the installer prints the line to add. Set MOONFOLD_VERSION to pin an exact version, for example MOONFOLD_VERSION=0.1.0-beta.1.

Run moonfold help or moonfold --help for the full reference. To start in a new working directory, use an explicit path such as moonfold ./my-project. A bare directory name is accepted only if it already exists.

If moonfold or moonfold start reports an already running server, connect to that server instead. Stop it before starting a replacement, or use a different --base-dir for an independent server.

Intel Macs

There is no moonfold executable for Intel Macs (the desktop app is available). To run a server there, build it from source with Node.js 24 and vp (Install vp):

git clone https://github.com/Mr-Dark-debug/Moonfold
cd moonfold && vp i && vp run build:desktop
node apps/server/dist/bin.mjs

moonfold update and the background service do not apply to a server run this way; update it with git pull and a rebuild.

Desktop app

Download a release from GitHub Releases. On Debian and Ubuntu, install the .deb with sudo apt install ./Moonfold-*.deb. Each release has a SHA256SUMS file if you want to check a download.

Opening an unsigned build

Beta builds are not code-signed yet, so the first launch shows a warning:

• macOS: open the .dmg and drag Moonfold to Applications. The first time, Control-click the app in Applications and choose Open, then Open again. If macOS only offers to move it to the Bin, open System Settings → Privacy & Security, find the note about Moonfold, and choose Open Anyway.
• Windows: SmartScreen shows "Windows protected your PC". Choose More info, then Run anyway.
• Linux: make the AppImage executable (chmod +x Moonfold-*.AppImage) and run it, or install the .deb.

You only need to do this once per install; updates open normally.

The .deb updates itself like the other desktop builds. It asks for your password to install each update. If your desktop has no password prompt, the update fails. Download the new .deb and install it the same way.

The moonfold command

The desktop app includes the moonfold command-line tool. To run it from any terminal, open Settings → General → About and choose Install next to moonfold command. On macOS and Linux it adds a moonfold link to a folder on your PATH; on Windows it adds the app's command folder to your PATH. Open a new terminal afterwards. Remove takes it off again. If you already have moonfold from npm, it stays as it is.

Windows Subsystem for Linux

Choose a WSL distro in Settings → Connections to run agents and projects there. Install the provider CLIs inside that distro. Moonfold installs its own server runtime there automatically; the first launch after an app update can take longer.

Open a project from a terminal

With the desktop app already running on the same machine:

moonfold app

This opens a new thread for the current directory, adding the project if needed. Pass a path, such as moonfold app ../my-project, to open another directory. It requires the desktop app, so a standalone server or an SSH session is not enough. If the command cannot reach the app, start or update the desktop app and try again.

Providers

Open Settings → Providers in the web or desktop app, select the environment, and enable the provider you want. Installation, login, and configuration belong to that environment's machine, even when you connect from a phone or another computer.

Provider CLIs must be on the server's PATH. If Moonfold cannot find one, set its Binary path in provider settings, especially when using a version manager. Cursor's executable is cursor-agent, although its login command is agent login. Codex connected through ChatGPT and Antigravity can use their managed runtimes without a PATH entry.

Moonfold warns when a provider version has known compatibility problems with your release. Check Settings → Providers on that environment for the recommended version or range. When its package manager supports installing a specific version, you can install the recommendation there. Otherwise use the provider's installer on the environment's machine. An unlisted version is unverified.

When a provider CLI is behind its latest release, its provider card shows the available version. Update now runs the installer that owns the CLI (Homebrew, or a global npm, pnpm, Yarn, Bun, Volta, or Vite+ install), or the CLI's own update command when Moonfold cannot tell. Update a CLI installed with mise through mise. Cursor and Antigravity update with Moonfold. Homebrew installs compare against the version Homebrew offers, which can trail the npm release by a few hours.

Add another provider instance for a separate account or configuration. Each instance can have its own environment variables, such as API keys or a custom base URL. Mark secret values as sensitive; after saving, Moonfold does not display their original values.

For provider-specific setup and accounts, see Codex, Claude, OpenCode, Antigravity, Pi, and Muse Code.

Next steps

• Working with threads: start tasks and organize parallel work.
• Permission modes: choose when agents ask before acting.
• Remote access: connect from another device.
• Running in the background: keep a Linux or macOS host available.
• Updating Moonfold: update the app and connected servers.

Edit this page on GitHub