moondesk 0.11.3 → 0.11.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +116 -139
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,87 +1,106 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
1
3
|
# MoonDesk
|
|
2
4
|
|
|
3
5
|
**Turn ChatGPT Chat into a local coding agent.**
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
Files, shell commands, browser automation, multiple workspaces, and session handoffs — through one local MCP host.
|
|
8
|
+
|
|
9
|
+
**No reverse engineering. No OpenAI API key. No separate agent service.**
|
|
10
|
+
|
|
11
|
+
[Quickstart](#quickstart) · [Features](#what-you-get) · [Safety](#safety) · [Contributing](#contributing)
|
|
6
12
|
|
|
7
13
|
```bash
|
|
8
14
|
npm install -g moondesk
|
|
9
15
|
```
|
|
10
16
|
|
|
17
|
+
</div>
|
|
18
|
+
|
|
11
19
|
> [!IMPORTANT]
|
|
12
|
-
> MoonDesk
|
|
20
|
+
> MoonDesk can execute commands and modify files on your computer. Use it only with workspaces and instructions you trust. For untrusted code, use a VM or container.
|
|
13
21
|
|
|
14
|
-
##
|
|
22
|
+
## What is MoonDesk?
|
|
23
|
+
|
|
24
|
+
MoonDesk is an open-source local MCP server that connects ChatGPT to your development environment.
|
|
15
25
|
|
|
16
|
-
|
|
26
|
+
Run it inside a project, connect the workspace URL to ChatGPT as a Custom Connector, and ChatGPT can work with that project using local tools.
|
|
17
27
|
|
|
18
28
|
```text
|
|
19
|
-
ChatGPT
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
29
|
+
ChatGPT
|
|
30
|
+
│
|
|
31
|
+
│ Custom Connector / MCP
|
|
32
|
+
▼
|
|
33
|
+
MoonDesk
|
|
34
|
+
├─ Files
|
|
35
|
+
├─ Shell jobs
|
|
36
|
+
├─ Browser / DevTools
|
|
37
|
+
├─ Workspaces
|
|
38
|
+
└─ Session handoffs
|
|
28
39
|
```
|
|
29
40
|
|
|
30
|
-
|
|
41
|
+
Your code stays on your machine unless a tool you run sends it somewhere else.
|
|
42
|
+
|
|
43
|
+
## What you get
|
|
44
|
+
|
|
45
|
+
| Capability | What it gives ChatGPT |
|
|
46
|
+
| --- | --- |
|
|
47
|
+
| **Files** | Read, search, edit, write, and delete inside a project workspace. |
|
|
48
|
+
| **Shell** | Run tests, builds, package installs, dev servers, Git, and other developer commands. |
|
|
49
|
+
| **Browser** | Control a dedicated Chromium session, inspect the DOM/console, emulate viewports, and visually inspect pages. |
|
|
50
|
+
| **Workspaces** | Serve multiple projects from one host, each with its own secret MCP URL. |
|
|
51
|
+
| **Handoffs** | Save continuation state when moving a long task to a fresh conversation. |
|
|
52
|
+
| **Permissions** | Use full local tools or a reduced read-only mode. |
|
|
53
|
+
| **Verified installs** | Download the matching native binary on first run and verify it against the release SHA-256. |
|
|
54
|
+
|
|
55
|
+
MoonDesk runs on **Windows, macOS, and Linux**.
|
|
56
|
+
|
|
57
|
+
## Why MoonDesk?
|
|
58
|
+
|
|
59
|
+
ChatGPT is already good at reasoning about code. MoonDesk gives it the local execution layer, so you can stop copying files into chat and pasting terminal output back and forth.
|
|
31
60
|
|
|
32
|
-
|
|
61
|
+
One MoonDesk process can serve several repositories at once:
|
|
33
62
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
- **Native binary distribution** — install with npm; MoonDesk downloads and verifies the matching release binary on first run.
|
|
41
|
-
- **Self-update** — global npm installs can update and restart from the TUI after confirmation.
|
|
63
|
+
```text
|
|
64
|
+
MoonDesk host
|
|
65
|
+
├── Project A ── secret MCP URL ──> D:\ProjectA
|
|
66
|
+
├── Project B ── secret MCP URL ──> D:\ProjectB
|
|
67
|
+
└── Project C ── secret MCP URL ──> D:\ProjectC
|
|
68
|
+
```
|
|
42
69
|
|
|
43
70
|
## Quickstart
|
|
44
71
|
|
|
45
72
|
### 1. Install
|
|
46
73
|
|
|
47
|
-
MoonDesk requires Node.js `^20.19.0 || ^22.12.0 || >=23
|
|
74
|
+
MoonDesk requires Node.js `^20.19.0 || ^22.12.0 || >=23`.
|
|
48
75
|
|
|
49
76
|
```bash
|
|
50
77
|
npm install -g moondesk
|
|
51
78
|
```
|
|
52
79
|
|
|
53
|
-
### 2.
|
|
54
|
-
|
|
55
|
-
Start MoonDesk inside the project you want to use:
|
|
80
|
+
### 2. Start it in your project
|
|
56
81
|
|
|
57
82
|
```bash
|
|
58
83
|
cd your-project
|
|
59
84
|
moondesk
|
|
60
85
|
```
|
|
61
86
|
|
|
62
|
-
Choose
|
|
63
|
-
|
|
64
|
-
- `Control Computer`
|
|
65
|
-
- `Control Browser`
|
|
66
|
-
- `Both`
|
|
87
|
+
Choose `Control Computer`, `Control Browser`, or `Both`.
|
|
67
88
|
|
|
68
|
-
On first launch, MoonDesk asks for
|
|
69
|
-
|
|
70
|
-
When upgrading on Windows from a version that previously used a conflicting `HOME\.moondesk\config.toml`, the next MoonDesk host startup migrates that existing config once into the canonical `%USERPROFILE%` location. The migration preserves the complete workspace registry and connector identities; it does **not** clear or recreate users' workspaces. If another process creates the canonical config during that migration, the canonical file wins and the legacy source is retained instead of being overwritten or deleted. A migration marker beside the legacy location prevents a stale legacy config from being imported again later if Windows could not remove it or another old process recreates it.
|
|
89
|
+
On first launch, MoonDesk asks for an **ngrok authtoken** and **static domain** and stores them in its local config.
|
|
71
90
|
|
|
72
91
|
### 3. Copy the workspace URL
|
|
73
92
|
|
|
74
|
-
Open `[w] Workspaces` in the TUI and copy the MCP URL
|
|
75
|
-
|
|
76
|
-
Each workspace has its own secret URL, for example:
|
|
93
|
+
Open `[w] Workspaces` in the TUI and copy the MCP URL:
|
|
77
94
|
|
|
78
95
|
```text
|
|
79
96
|
https://your-domain.ngrok-free.dev/<workspace-secret>/mcp
|
|
80
97
|
```
|
|
81
98
|
|
|
82
|
-
|
|
99
|
+
> Treat this URL like a credential.
|
|
100
|
+
|
|
101
|
+
### 4. Add it to ChatGPT
|
|
83
102
|
|
|
84
|
-
|
|
103
|
+
Create a Custom Connector:
|
|
85
104
|
|
|
86
105
|
```text
|
|
87
106
|
Name: MoonDesk · <project name>
|
|
@@ -89,124 +108,76 @@ MCP Server URL: <URL copied from MoonDesk>
|
|
|
89
108
|
Authentication: None
|
|
90
109
|
```
|
|
91
110
|
|
|
92
|
-
|
|
111
|
+
Allow write actions only when you trust the workspace and task.
|
|
93
112
|
|
|
94
113
|
### 5. Add the recommended instruction
|
|
95
114
|
|
|
96
|
-
Add this to your ChatGPT custom instructions:
|
|
97
|
-
|
|
98
115
|
```text
|
|
99
116
|
MoonDesk is a coding tool and a custom connector. Always use MoonDesk if the user wants to do anything related to file operations. Always call `moondesk_instruction` after `list_resources`, and follow the instructions it contains.
|
|
100
117
|
```
|
|
101
118
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
### Windows security software
|
|
105
|
-
|
|
106
|
-
MoonDesk verifies the downloaded native binary against the SHA-256 published with the matching GitHub Release before launching it. If Windows Security or another antivirus quarantines that verified executable, update its security definitions and check Protection History, then run `moondesk` again. Do not disable antivirus protection or exclude the whole MoonDesk directory just to bypass a detection; report suspected false positives with the exact release version and SHA-256 instead.
|
|
119
|
+
Select the connector and start working.
|
|
107
120
|
|
|
108
|
-
##
|
|
121
|
+
## Browser control
|
|
109
122
|
|
|
110
|
-
|
|
123
|
+
MoonDesk owns a dedicated agent browser instead of attaching to your personal browser profile. It starts lazily, runs headless by default, and can be switched to visible mode for human-assisted steps such as logins or permission prompts.
|
|
111
124
|
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
├── Project A -> /<secret-A>/mcp -> D:\ProjectA
|
|
118
|
-
├── Project B -> /<secret-B>/mcp -> D:\ProjectB
|
|
119
|
-
└── Project C -> /<secret-C>/mcp -> D:\ProjectC
|
|
125
|
+
```bash
|
|
126
|
+
moondesk browser navigate_page --url=http://localhost:3000
|
|
127
|
+
moondesk browser emulate --viewport=390x844x1,mobile,touch
|
|
128
|
+
moondesk browser take_snapshot
|
|
129
|
+
moondesk browser list_console_messages
|
|
120
130
|
```
|
|
121
131
|
|
|
122
|
-
|
|
132
|
+
Use `view_page` when the task depends on actual rendered pixels rather than only a text/accessibility snapshot.
|
|
123
133
|
|
|
124
|
-
|
|
134
|
+
For browser-runtime invariants and implementation details, see [`docs/BROWSER_RUNTIME_ARCHITECTURE_HARDENING.md`](docs/BROWSER_RUNTIME_ARCHITECTURE_HARDENING.md).
|
|
125
135
|
|
|
126
|
-
|
|
136
|
+
## Workspaces and handoffs
|
|
127
137
|
|
|
128
|
-
|
|
138
|
+
Each workspace keeps its own root, secret connector URL, command jobs, retained output, history, and handoff state. Use `[w] Workspaces` to add, rename, inspect, copy, rotate, or remove projects.
|
|
129
139
|
|
|
130
|
-
|
|
140
|
+
Handoffs are explicit checkpoints. `create_handoff` saves the task goal, completed work, decisions, validation, blockers, next steps, Git state, and current MoonDesk jobs. `resume_handoff` reloads the checkpoint and checks for drift; `complete_handoff` marks the continuation finished.
|
|
131
141
|
|
|
132
|
-
|
|
142
|
+
> [!CAUTION]
|
|
143
|
+
> Never put credentials, tokens, passwords, private keys, or other secrets in handoff text.
|
|
133
144
|
|
|
134
|
-
|
|
145
|
+
Stopping the MoonDesk host disconnects every active workspace connector, so shutdown from the live dashboard requires confirmation.
|
|
135
146
|
|
|
136
|
-
|
|
147
|
+
## Safety
|
|
137
148
|
|
|
138
|
-
|
|
149
|
+
Dedicated file tools stay inside the selected workspace and reject path traversal plus symlink/junction escapes.
|
|
139
150
|
|
|
140
|
-
|
|
151
|
+
Shell tools are different:
|
|
141
152
|
|
|
142
|
-
|
|
153
|
+
> `run_command` and `start_command` execute your normal developer shell with the workspace as its working directory. They inherit your normal environment, credentials, `PATH`, and OS permissions.
|
|
143
154
|
|
|
144
|
-
|
|
145
|
-
| --- | --- |
|
|
146
|
-
| `moondesk_instruction` | MoonDesk usage guidance and active-handoff discovery |
|
|
147
|
-
| `create_handoff` | Persist a workspace-scoped session checkpoint |
|
|
148
|
-
| `resume_handoff` | Load a checkpoint and verify current Git/job drift |
|
|
149
|
-
| `complete_handoff` | Mark a continuation finished |
|
|
150
|
-
| `read` | Read workspace or explicitly addressed local files |
|
|
151
|
-
| `view_image` | Inspect one local image with model vision |
|
|
152
|
-
| `view_images` | Inspect several local images together |
|
|
153
|
-
| `search` | Search workspace text |
|
|
154
|
-
| `write` | Create or overwrite files |
|
|
155
|
-
| `edit` | Replace exact text |
|
|
156
|
-
| `delete` | Delete files or directories |
|
|
157
|
-
| `run_command` | Run a short shell command |
|
|
158
|
-
| `start_command` | Start a background command |
|
|
159
|
-
| `list_commands` | List current and retained jobs |
|
|
160
|
-
| `poll_command` | Read incremental job output |
|
|
161
|
-
| `read_command_output` | Read preserved command output |
|
|
162
|
-
| `cancel_command` | Stop a job and its process tree |
|
|
163
|
-
|
|
164
|
-
Use `run_command` for short work. Use `start_command` + `poll_command` for builds, tests, package installs, dev servers, and other long-running commands. Polls long-wait by default and report elapsed, idle, and timeout timing so agents can avoid rapid blind polling.
|
|
165
|
-
|
|
166
|
-
`read-only` mode removes workspace mutation/shell tools and MoonDesk metadata mutation tools such as `create_handoff`, `resume_handoff`, and `complete_handoff`. `moondesk_instruction` can still report that an active handoff exists. In Browser/Both mode, read-only also permits bounded browser inspection while state-changing browser commands and browser file-output flags remain blocked.
|
|
167
|
-
|
|
168
|
-
Browser mode has a stable tool catalog instead of forwarding the full Chrome DevTools MCP schema:
|
|
169
|
-
|
|
170
|
-
| Browser tool | Purpose |
|
|
171
|
-
| --- | --- |
|
|
172
|
-
| `set_browser_presentation` | In `multi-tools`, request headless or visible presentation; live-session changes require explicit restart confirmation |
|
|
173
|
-
| `browser_command` | Run one browser/DevTools CLI operation in the shared lazy session |
|
|
174
|
-
| `view_page` | Attach the current rendered page directly to the model as bounded image content |
|
|
155
|
+
**The workspace directory is not an OS sandbox.**
|
|
175
156
|
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
The same `moondesk` CLI also has a `browser` subcommand for deterministic scripted flows in `Both` mode:
|
|
179
|
-
|
|
180
|
-
```bash
|
|
181
|
-
moondesk browser skill
|
|
182
|
-
moondesk browser navigate_page --url=http://localhost:3000
|
|
183
|
-
moondesk browser emulate --viewport=390x844x1,mobile,touch
|
|
184
|
-
moondesk browser take_snapshot
|
|
185
|
-
moondesk browser list_console_messages
|
|
186
|
-
```
|
|
157
|
+
Use read-only mode when mutation is unnecessary, and use a VM or container for untrusted code.
|
|
187
158
|
|
|
188
|
-
|
|
159
|
+
> [!CAUTION]
|
|
160
|
+
> Never share a workspace MCP URL. Anyone who can use it may be able to invoke the tools you exposed.
|
|
189
161
|
|
|
190
|
-
|
|
162
|
+
## Reference
|
|
191
163
|
|
|
192
|
-
|
|
164
|
+
<details>
|
|
165
|
+
<summary><strong>Tools</strong></summary>
|
|
193
166
|
|
|
194
|
-
|
|
167
|
+
**Guidance / handoffs:** `moondesk_instruction`, `create_handoff`, `resume_handoff`, `complete_handoff`
|
|
195
168
|
|
|
196
|
-
|
|
169
|
+
**Files:** `read`, `view_image`, `view_images`, `search`, `write`, `edit`, `delete`
|
|
197
170
|
|
|
198
|
-
**
|
|
171
|
+
**Commands:** `run_command`, `start_command`, `list_commands`, `poll_command`, `read_command_output`, `cancel_command`
|
|
199
172
|
|
|
200
|
-
|
|
173
|
+
**Browser:** `set_browser_presentation`, `browser_command`, `view_page`
|
|
201
174
|
|
|
202
|
-
|
|
203
|
-
- a VM or container when you need OS-level isolation;
|
|
204
|
-
- secret rotation from `[w] Workspaces` if a workspace MCP URL is ever exposed.
|
|
175
|
+
Use `run_command` for short work. Use `start_command` + `poll_command` for builds, tests, installs, dev servers, and other long-running jobs.
|
|
205
176
|
|
|
206
|
-
>
|
|
207
|
-
> Never share a workspace MCP URL. Treat it like a credential.
|
|
177
|
+
</details>
|
|
208
178
|
|
|
209
|
-
|
|
179
|
+
<details>
|
|
180
|
+
<summary><strong>Configuration</strong></summary>
|
|
210
181
|
|
|
211
182
|
| Setting | Default / location |
|
|
212
183
|
| --- | --- |
|
|
@@ -215,38 +186,44 @@ Use:
|
|
|
215
186
|
| Port override | `PORT` |
|
|
216
187
|
| Initial workspace override | `WORKSPACE_ROOT` |
|
|
217
188
|
| Global instructions | `~/.moondesk/AGENTS.md` |
|
|
218
|
-
|
|
|
189
|
+
| Workspace instructions | `<workspace>/AGENTS.md` |
|
|
219
190
|
| Codex-compatible instructions | `~/.codex/AGENTS.md` |
|
|
191
|
+
| Session handoffs | `%USERPROFILE%\.moondesk\handoffs\<workspace-id>\` on Windows; `$HOME/.moondesk/handoffs/<workspace-id>/` on macOS/Linux |
|
|
192
|
+
|
|
193
|
+
Workspace `AGENTS.md` instructions take priority.
|
|
220
194
|
|
|
221
|
-
|
|
195
|
+
On macOS Terminal.app, set `MOONDESK_SKIP_MACOS_TERMINAL_PROFILE=1` to disable MoonDesk's dedicated Terminal profile behavior.
|
|
222
196
|
|
|
223
|
-
|
|
197
|
+
</details>
|
|
198
|
+
|
|
199
|
+
<details>
|
|
200
|
+
<summary><strong>Windows antivirus note</strong></summary>
|
|
201
|
+
|
|
202
|
+
MoonDesk verifies the downloaded native executable against the SHA-256 published with the matching GitHub Release before launching it.
|
|
203
|
+
|
|
204
|
+
If Windows Security or another antivirus quarantines the verified executable, update security definitions and check **Protection history**, then run `moondesk` again. Do not disable antivirus protection or exclude the entire MoonDesk directory just to bypass a detection.
|
|
205
|
+
|
|
206
|
+
</details>
|
|
224
207
|
|
|
225
208
|
## Stack
|
|
226
209
|
|
|
227
210
|
| Part | Technology |
|
|
228
211
|
| --- | --- |
|
|
229
212
|
| Core | Rust |
|
|
230
|
-
|
|
|
213
|
+
| Server / async runtime | Axum + Tokio |
|
|
231
214
|
| TUI | Ratatui |
|
|
232
215
|
| Tunnel | ngrok |
|
|
233
216
|
| MCP server | Custom implementation |
|
|
234
217
|
| MCP protocol | `2025-11-25` |
|
|
235
|
-
| Browser runtime | pinned `chrome-devtools-mcp@1.7.0`
|
|
236
|
-
| Distribution | npm + native binaries |
|
|
218
|
+
| Browser runtime | pinned `chrome-devtools-mcp@1.7.0` |
|
|
219
|
+
| Distribution | npm + verified native binaries |
|
|
237
220
|
|
|
238
221
|
## Contributing
|
|
239
222
|
|
|
240
|
-
Contributions are welcome.
|
|
241
|
-
|
|
242
|
-
Release maintainers should also read [`docs/RELEASING.md`](docs/RELEASING.md).
|
|
243
|
-
|
|
244
|
-
## ClippyMoon
|
|
223
|
+
Contributions are welcome.
|
|
245
224
|
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
<em>ClippyMoon!</em>
|
|
249
|
-
</p>
|
|
225
|
+
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — development setup, required checks, and PR rules
|
|
226
|
+
- [`docs/RELEASING.md`](docs/RELEASING.md) — release pipeline and maintainer guidance
|
|
250
227
|
|
|
251
228
|
## Disclaimer
|
|
252
229
|
|