Windows: “Windows protected your PC”Link to the Windows: “Windows protected your PC” section
The Moon Desktop installer and portable version are signed by STELLARR STUDIO. A new publisher builds its reputation with SmartScreen over time, so for now this warning can still appear when you open a file downloaded from the Moon Desktop page on realmoon.ai. If it does:
- Click “More info”.
- Check that the publisher shown is STELLARR STUDIO, and that the file name matches the one you downloaded. To go further, compare its checksum with the published one: see Verify a file.
- Click “Run anyway”.
If the publisher shown is “Unknown publisher” or any name other than STELLARR STUDIO, don’t open the file: delete it and download it again from realmoon.ai. Never open a Moon Desktop installer you received by email or downloaded anywhere other than realmoon.ai. A company antivirus can also block the installer: ask your IT department.
Moon CLI, which comes with the app, has also been signed by STELLARR STUDIO since Moon CLI 0.5.3, and Moon Desktop checks its release signature before installing it. If Windows blocks it anyway (Smart App Control, antivirus), see Antivirus, SmartScreen and Smart App Control.
On MacLink to the On Mac section
Moon Desktop for Mac is notarized by Apple, so Gatekeeper, the macOS app check, accepts it. The first time, macOS may ask you to confirm, as it does for any app downloaded from the internet: click “Open”.
macOS won’t open the appLink to the macOS won’t open the app section
If macOS refuses to open Moon Desktop, or says it is damaged, don’t work around the alert: no “Open Anyway”, no command in Terminal.
- Drag Moon Desktop from the Applications folder to the Trash, and delete the downloaded disk image.
- Download the disk image again from the Moon Desktop page on realmoon.ai. To go further, compare its checksum with the published one: see Verify a file.
- Drag Moon Desktop onto the Applications folder, then open it from that folder.
If the alert comes back, don’t open the app, and contact support (see below). Never install a Mac version found anywhere other than realmoon.ai.
Moon CLI on MacLink to the Moon CLI on Mac section
The Mac app doesn’t include Moon CLI. At the Moon CLI step of the welcome assistant (Help menu › “Welcome assistant…”), “Download and install Moon CLI” downloads it from realmoon.ai, checks its signature, then installs it for your account. Nothing is downloaded until you click. Then open a new terminal to use Moon CLI.
- “Moon CLI could not be downloaded (…). Check your connection, then try again.”: check your connection, then try again. Behind a company proxy, the address
https://must be reachable.realmoon.ai/ dl/ - You can also install it from Terminal: see Install Moon CLI.
Screen capture on MacLink to the Screen capture on Mac section
“Allow Moon Desktop to record the screen”: macOS asks for this permission for screen capture.
- Click “Open Settings”, or open “System Settings” › “Privacy & Security” › “Screen Recording”.
- Turn on Moon Desktop.
- If macOS asks you to reopen Moon Desktop, do so, then take the screenshot again.
Linux: the AppImage won’t openLink to the Linux: the AppImage won’t open section
- Make the file executable:
chmod, or in the file’s properties, “Allow executing file as program”.+x MoonDesktop-*.AppImage - If nothing happens, or a message mentions FUSE, install the FUSE 2 library:
sudo apt install libfuse2sudo apt install libfuse2t64sudo dnf install fuse-libsThe .deb package doesn’t need FUSE: sudo . It doesn’t update itself.
Ctrl+A or Ctrl+Z closes Moon DesktopLink to the Ctrl+A or Ctrl+Z closes Moon Desktop section
Before Moon Desktop 2.0.3, on Windows and Linux with a French (AZERTY) keyboard, CtrlA (select all) quit the app and CtrlZ (undo) closed the window: the app read the key’s position on an English keyboard, where it is Q or W, instead of the letter it types. Quitting also stopped any work Moon was doing in Code.
Update Moon Desktop to 2.0.3 or later: see The update doesn’t install. From that version, shortcuts follow the letter the key types, and reloading, closing or quitting while Moon is working asks you to confirm first (see “Moon is still working”). On Mac, shortcuts go through the system menu bar, so they were not affected.
The quick window shortcut doesn’t workLink to the The quick window shortcut doesn’t work section
A “Shortcut unavailable” notification tells you at launch: “Alt+Space is already used by another application. Pick another one in the app settings.” Another application has already taken this shortcut: on Windows, for example, PowerToys Run, ChatGPT and Copilot also use AltSpace.
- Open “Settings” › “Moon Desktop” › “Keyboard shortcuts”.
- On the “Quick window” row (or “Screenshot”), click “Change”, then press the new shortcut, for example AltShiftM. Don’t try CtrlAlt: it is the AltGr key on many keyboards, and Moon Desktop refuses it.
Even simpler: the welcome assistant (☰ menu › Help › “Welcome assistant…”; on Mac, the Help menu), at the “The gestures of Moon Desktop” step, sees that the shortcut is taken and offers “Use Alt+Shift+M” (or another free shortcut): one click is enough. It is the fastest fix when PowerToys has taken AltSpace.
The “Quick settings” submenu of the File menu (on Mac, of the Moon Desktop menu) only offers the default shortcut, the one already chosen in the settings, or “None”: to choose another one, go through “Settings” › “Moon Desktop”.
| Message | What it means |
|---|---|
| “Another app already uses this shortcut (ChatGPT or Copilot, for example). Choose another one.” | The saved shortcut was taken by another application before Moon Desktop started: choose another one. |
| “This shortcut is already used by another application.” | The shortcut you just chose is taken: choose another one. The previous one stays active. |
| “Ctrl+Alt is the AltGr key on many keyboards…” | CtrlAlt types €, @ or # on a French keyboard: use AltShift instead. |
| “… two modifier keys, one of them Alt or Shift (for example Alt+Shift+Space).” | For “Open Moon with what I copied” and “Dictate”: two modifier keys, one of them Alt or Shift, then a key. |
| “This shortcut is already used for editing (copy, paste, undo…): pick another one.” | It would already be in use in all your applications. |
| “Each app shortcut must be different from the others.” | Two Moon Desktop shortcuts can’t be the same. |
| “This shortcut is reserved by the system.” | The system keeps it for itself. |
| “Add Ctrl or Alt to the key.” | A single key (or one with Shift only) isn’t a shortcut, except the F1 to F24 keys. |
The quick window and screen capture are also available from the icon in the notification area (the menu bar on Mac).
The update doesn’t installLink to the The update doesn’t install section
- “Restart to update” is shown: click it, or quit Moon Desktop. The update installs when the app closes.
- “The update check did not succeed.”: check your connection, then try again later from the Help menu › “Check for updates”. Behind a company proxy, the address
https://must be reachable.realmoon.ai/ dl/ desktop/ - “Automatic updates are not available in this version.”: this is the Windows portable version or the
.debpackage. Download the new version from the Moon Desktop page.
“Moon is still working” before reloading, closing or quittingLink to the “Moon is still working” before reloading, closing or quitting section
Since Moon Desktop 2.0.3, reloading the page, closing a window, quitting the app or “Restart to update” (and, since 2.1, “Back” and “Forward” to a page that reloads) ask you to confirm first when Moon is working in Code or a terminal of the code tool is running. “Cancel” is selected by default: Enter and Esc cancel.
| Message | What to do |
|---|---|
| “Moon is still working in this window” or “Moon is still working” | Moon is answering, or waiting for your permission. “Cancel” lets it finish; “Reload anyway”, “Close anyway” or “Quit anyway” stops it in the middle of its work. Files already changed stay as they are. |
| “A terminal is still running in this window”, “Terminals are still running in the code tool”… | A terminal of the code tool is still open, even with no command running: continuing stops it, along with whatever runs in it (a development server, for example). |
| “Restarting for the update stops…” | “Cancel” keeps your work: the update will install when Moon Desktop closes. “Restart anyway” installs it right away. |
| “Changing page reloads this window and stops…” | “Back” or “Forward” (or Alt←, Alt→) leads to a page that reloads (Moon Desktop 2.1). “Cancel” stays on the page; “Change page anyway” goes there, and stops whatever is running. |
“Quit” from the macOS Dock and signing out of your session on the computer don’t ask anything. See Reload, close or quit while Moon is working.
A panel disappearedLink to the A panel disappeared section
In the code tool, a panel you hid or moved comes back from the “Panel layout” menu (Moon Desktop 2.1): its button is at the bottom of the activity bar, and the same button in the title bar opens it too.
- Open “Panel layout”.
- Check “Show the side panel” or “Show the terminal”. If the conversation takes up all the space, uncheck “Conversation only”.
- To put everything back as it was at first (side panel on the left, terminal at the bottom, conversation on the right), choose “Back to the default layout”.
With the keyboard: CtrlB shows the side panel, Ctrl` the terminal (Ctrl² on a French keyboard; ⌘ instead of Ctrl on Mac). A panel that is too narrow says “Enlarge this area to show the terminal.” or “… the Git view.”: drag its edge, or make the window bigger. See Arrange the panels.
The sidebar, Chat | Code or “Search” disappearedLink to the The sidebar, Chat | Code or “Search” disappeared section
Since Moon Desktop 2.1, they are in the title bar, at the top of the window: the sidebar button (“Show the sidebar”), the Chat | Code switch and “Search”. With the keyboard, CtrlShiftS shows or hides the sidebar, and CtrlK opens “Search” (⌘ on Mac). In a very narrow window, Moon AI switches to its phone navigation: “Open menu”, at the top left of the page, opens the sidebar.
In a narrow window, the title bar labels move into tooltips, and the buttons of the Code session can drop out for lack of space: make the window bigger to bring them back. While a permission window is open, the bar only shows the Moon Desktop buttons. See The title bar.
The app won’t start or stays on a loading screenLink to the The app won’t start or stays on a loading screen section
- An “offline” screen with “Try again”: the computer has no network. Moon Desktop goes back to Moon AI on its own as soon as the network returns.
- “Moon AI is not responding”: the service can’t be reached right now; the app retries on its own, at longer and longer intervals. Check the service status.
- Nothing opens: Moon Desktop only runs one copy at a time. Look for its icon in the notification area (the menu bar on Mac) and click “Open Moon Desktop”.
- The app closes right away: restart the computer, then reinstall Moon Desktop. If it keeps happening, contact support and attach the app log:
main.log, in thelogsfolder of the Moon Desktop data (%APPDATA%\Moonon Windows,Desktop\logs ~/on macOS,Library/ Application Support/ Moon Desktop/ logs ~/on Linux). The log doesn’t contain the text of your conversations..config/ Moon Desktop/ logs
Code won’t startLink to the Code won’t start section
See If Code won’t start and Troubleshooting Moon CLI.
The code toolLink to the The code tool section
The messages of the Moon Desktop 2.0 code tool (explorer, editor, Git view, terminal, preview), and what they ask you to do. The tool itself is described in Code in Moon Desktop.
Folder trustLink to the Folder trust section
| Message | What to do |
|---|---|
| “Do you trust the source of this folder?” | Moon Desktop starts neither Moon CLI, nor Git, nor a terminal in a folder until you answer. If you know where it comes from, click “Trust this folder” in the Moon Desktop window. See Trust a folder. |
| “This folder is not trusted yet.” or “Trust this folder to send a message.” | You answered “Not now”: click “Trust this folder” when you’re ready. |
| “Trust the folder first.” | “Open in editor” and the preview wait for trust: trust the folder first. |
| “This folder is not trusted. Moon CLI, Git and the terminal do not start there without your authorization.” | Click “Try again”, then answer “Trust this folder” in the Moon Desktop window. |
| “Trust for this folder was removed in the app settings. Moon CLI stopped.” | Click “Restart Moon CLI”: the question is asked again. |
| “Trust this folder to use the terminal.” or “Trust this folder to use Git.” | The folder isn’t trusted yet: click “Trust…”, then answer in the Moon Desktop window. In the Git view, “Not now” folds the question into this line. |
| “This folder cannot be trusted”, with “Its Git repository is elsewhere, on the network: Moon Desktop does not connect to it.” | The folder’s .git file points to a repository on a network share, which Moon Desktop never contacts. Remove or fix this .git file, then reopen the folder. |
| “This folder cannot be trusted”, with “Its .git file could not be read the way Git reads it:” | The folder’s .git file is unreadable, too large or malformed: remove or fix it, then reopen the folder. |
| “This folder cannot be trusted”, with “Its .git file points to a folder that is not a Git repository (Git refuses it too):” | Since Moon Desktop 2.1. The folder’s .git file points to an arbitrary folder, often in a downloaded archive: Git itself doesn’t use it. Remove this .git file, then reopen the folder. |
| “This folder cannot be trusted”, with “Its Git repository would be a far too broad folder (root of a drive, parent folder, home folder, Documents…):” | Since Moon Desktop 2.1. No real repository keeps its Git folder there: trust would cover everything it contains. Remove or fix the folder’s .git file, then reopen it. |
“A network folder (\\server\share) does not open from File Explorer…” | Use the share’s drive letter, or open the folder in Code with “Open a folder”. |
| “Open the trust question with a click.” | The question only opens right after your click: click “Trust this folder” again. |
PanelsLink to the Panels section
| Message | What to do |
|---|---|
| “Enlarge this area to show the terminal.” or “Enlarge this area to show the Git view.” | The area is too small for Moon Desktop to show the panel there: drag its edge, or make the window bigger. |
| “Click here to start the terminal.” or “Click to start a terminal in this folder.” | The terminal only starts when you click in its area, never on a key press. |
| “Click in the terminal to type in it.” | The terminal gave up the keyboard, because you clicked elsewhere or its area moved: click in its area. A highlighted border shows when it has the keyboard. |
| “Paste several lines?” | Each line of the text can run a command: only paste it if you know where it comes from. |
| “Confirm this action?” | The panel had just appeared, moved or received the keyboard from the page: check that the action shown is the one you want, then click “Confirm”. After “The panel moved during the confirmation: try again.”, repeat the gesture. |
| “Push the commits?” | “Push” always asks for this confirmation, with the name of the branch going to the remote repository. |
| “Create the PR” is grayed out | The reason is written under the button: “This repository has no remote: /pr pushes the branch to GitHub.”, “Moon CLI is not running in this folder: open a Moon session.” or “Creating the PR needs Moon CLI 0.5.0 or later: update Moon CLI.” Fix that, then click again. Since Moon Desktop 2.0.3, the button doesn’t appear in a folder that isn’t trusted, without Git, or outside a Git repository: the Git view then tells you what to do. |
| “Your message to Moon is not empty. Send it or clear it, then click Create the PR again.” | “Create the PR” never replaces what you wrote or attached: send this message, or clear it, then click the button again. |
| “Paste control characters?” | The copied text contains control characters (Esc, Ctrl+O…) that can run a command in the terminal without you pressing Enter; a web page may have filled the clipboard. “Paste without them” removes them; only choose “Paste as is” if you know where the text comes from. |
| “Git is not installed” | Click “Download Git”, or use the welcome assistant (☰ menu › Help › “Welcome assistant…”; on Mac, the Help menu). Git installed while the app is running is found without restarting it. |
| “No Git repository” | The folder isn’t a Git repository: “Initialize a repository” creates one. |
| “The version before Moon is not known for this file (Git is required). Use /undo, or Git.” | The file is secret, ignored by .gitignore or too large, or Git is missing: undo it with /undo, or in the Git view. |
| “This file changed on disk since it was opened: your version was not saved.” | “Compare” shows both versions; “Overwrite” saves yours. |
| “This file is not UTF-8: it is opened read-only so it is not damaged.” | The editor only changes files in UTF-8 or UTF-16: ask Moon to make the change, or make it in another editor. |
| “The search took too long and was stopped: narrow it.” | Make the search text more specific, or fill in “Files to include” and “Files to exclude”. |
| “Open the editor with a click.”, “Open the folder with a click.” or “Open the terminal with a click.” | Moon Desktop only opens these tools right after your click: click the button again. |
| “A code view crashed. Reopening it.” | Nothing to do: the view reopens on its own. If it happens often, contact support. |
| “This view could not be opened.” | Click “Try again”. |
The previewLink to the The preview section
| Message | What to do |
|---|---|
| “Open this address in the preview with a click.” | A local address only opens in the preview when you click: click “Open preview”, under the message. |
| “Show this address in the preview?” (“Open this address in the preview?” before Moon Desktop 2.0.3) | Since Moon Desktop 2.0.2, a local address never opened for this folder is confirmed in this window. Click “Open in the preview” if it is the address you just asked for (your development server); otherwise, “Cancel”. |
| “Address not opened in the preview.” | You answered “Cancel”: open the preview of this address again so the question is asked again. |
| “Let the preview reach this service?” | The page shown in the preview is sending a request to a service on your computer (its API on another port, for example), or to an address on your local network or a VPN, that you haven’t opened for this folder. If it is part of your project, click “Allow for this folder”, then reload the preview: the blocked request isn’t sent again. The permission covers the page’s requests, not showing this service in the preview. Otherwise, “Refuse”. See What the preview can reach. |
| “To confirm, move the pointer off the button, then come back and click it. With the keyboard: Tab, then Enter.” (before Moon Desktop 2.0.3: “To accept, leave the button then come back to it, with the pointer or the Tab key.”) | The click on “Allow for this folder” didn’t count: the pointer has to enter the button after the window appears. Move it off the button, come back, then click; or reach the button with Tab, then Enter. On a touch screen, a tap alone isn’t enough: use the mouse, the touchpad or the keyboard. |
| The preview site can’t reach its API, with no question | You may have refused the question: for this service, in this folder, it only comes back after Moon Desktop closes. Quit and restart the app. It isn’t asked either for a preview that is hidden, too small or covered (show all of it, then reload it), nor more than five times per folder and per app launch. Or the API is called through another form of the computer’s address (0.0.0.0, its network address, a name that leads to it) or over https, which don’t trigger the question: call it through localhost or 127.0.0.1, over http. |
| “Another preview or a panel of the code tool covers the preview: show all of it to capture it.” (or “… to pick an element in it.”) | A capture is only taken of a preview that is fully visible: close or move the panel or the other preview covering it, then try again. |
| “The preview just appeared or moved: try again in a moment.” | The preview was just placed, moved, resized, or showed another page: wait a moment, then try again. |
| “Pick an element” or “Create the PR” doesn’t appear | These buttons need Moon Desktop 2.0.2 or later: see The update doesn’t install. Since 2.0.3, “Create the PR” also only appears in a Git repository of a trusted folder. |
| “Pick an element of the preview with a click.” | “Pick an element” only starts right after your click on the button (or Enter, never Space): click “Pick an element” again. |
| “The preview is hidden or too small: show it to pick an element in it.” | Show the preview tab and make it bigger, then click “Pick an element” again. |
| “The preview is not responding: reload it, then try again.” | The preview page is still loading, or isn’t responding: click “Reload”, then “Pick an element”. |
| “Write what Moon should do with this element.” | A picked element is never sent on its own: write your request, then send. |
| “Up to four preview elements per message.” or “Up to four images per message. Remove one to add this element.” | Send this message, or remove an attachment, then pick the next elements. |
| “Attach the capture of the preview with a click.” | Click “Attach a screenshot of the preview” again. |
| “The preview is hidden or too small: show it to capture it.” | Show the preview tab, make it bigger, then take the capture again. |
| “Only local addresses (localhost) and files in this folder open in the preview.” | For any other address, use “Open in the browser”. |
| “Nothing answers at this address. Is the development server running?” | Start the development server, for example in the terminal, then click “Reload”. |
| “This address cannot be reached. Check that it is correct and that the service is running.” | Check the address and its port, and that the service is running, then click “Reload”. |
| “This address did not answer in time. The service may be busy: try again.” | Wait for the service to finish starting, then click “Reload”. |
| “This page was not loaded in the preview: it was blocked.” | Loading was refused, by the preview or by a security rule of the page itself. “Reload” isn’t offered: the page would be refused again. The technical detail, in small print below, says why. |
| “The preview page stopped. Reload the preview.” | Click “Reload”. |
| “The preview page could not load.” | Read the technical detail, in small print below, then click “Reload”. |
| “The window is too narrow for the preview.” | Make the Moon Desktop window bigger. |
| “The preview needs a newer version of Moon Desktop.” | Update Moon Desktop: see The update doesn’t install. |
Contact supportLink to the Contact support section
Write to contact@stellarrstudio.com with your system, the Moon Desktop version (Help menu › “About Moon Desktop”; on Mac, Moon Desktop menu › “About Moon Desktop”) and the exact message. The Help menu › “Write to the Moon AI team” opens this email in your mail app, with the version already in the subject. See also Get help.