@arcane-fly/desktop-monkey 0.1.7 → 0.1.11

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.
Files changed (2) hide show
  1. package/README.md +120 -2
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -16,6 +16,9 @@ done/asked count.
16
16
  2. **Troop mesh** — concurrent coordination of several machines: *primary + support*, *several
17
17
  supports*, rings and chains. Work is split so that no single machine has to carry the compute,
18
18
  GPU memory, RAM or disk. See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
19
+ A sleeping machine is woken for waiting work, and a machine is kept awake, only when its owner
20
+ switched that on for it (`dmonkey power`, or the dashboard's Devices tab;
21
+ [ADR 0008](docs/adr/0008-device-wake-and-keep-awake.md)).
19
22
  3. **Hooks** — an improved, typed, auditable hook engine (lessons from Claude Code, Codex and
20
23
  Cursor hooks) that also fires on mesh events.
21
24
  4. **Monkey Monitor entry point** — the local GTK app
@@ -63,8 +66,123 @@ current health is in [`docs/STATUS.md`](docs/STATUS.md).
63
66
 
64
67
  Devices and MCP clients connect to the public URL above; `RELAY_PUBLIC_URL` is set
65
68
  on the Railway `relay` service so the OAuth issuer matches. The image is built from
66
- the repo `Dockerfile` (`pip install '.[relay]'`), which pins the relay extras the
67
- platform builder would otherwise skip.
69
+ the repo `Dockerfile` (`pip install '.[relay,qig]'`), which pins the relay extras the
70
+ platform builder would otherwise skip. The `qig` extra (qig-compute) is there because the relay
71
+ recomputes screened-QFI answers itself and refuses those jobs without it.
72
+
73
+ ## Start the agent at login, and the switch for remotes
74
+
75
+ Once a device is linked (`dmonkey service link`, or the first `dmonkey remote`), one command makes
76
+ it come back by itself after every restart and login, with no prompt:
77
+
78
+ ```
79
+ dmonkey autostart enable # start at login, and now
80
+ dmonkey autostart status # installed / enabled / running / connected, and the exact command it runs
81
+ dmonkey autostart disable # stop it and remove the login entry
82
+ ```
83
+
84
+ | Platform | What `enable` installs |
85
+ |---|---|
86
+ | Linux | systemd user unit (`~/.config/systemd/user/desktop-monkey-agent.service`), restarted if it stops. Starts at login; for start at boot, before login, run once yourself: `loginctl enable-linger` |
87
+ | Windows | per-user Scheduled Task "Desktop Monkey Agent" at your logon: no administrator rights, no window. Falls back to a launcher in your Startup folder if Task Scheduler refuses. Whether Windows restarts the agent after a crash is unverified: assume it does not |
88
+ | macOS | LaunchAgent `com.github.arcane-fly.desktop-monkey.agent`, restarted if it stops |
89
+
90
+ The login entry holds no credential: it runs `dmonkey remote --foreground --unattended --server <relay>`
91
+ and the agent reads its stored link itself. If the link is missing, unusable or was revoked, the
92
+ agent waits, disconnected, and `status` says so; it never asks for approval in a session nobody can
93
+ see. Only one agent runs per device: a second `dmonkey remote` exits with a line naming the first,
94
+ and `enable` stops one you started by hand.
95
+
96
+ **Remote connections are allowed from the moment a device is linked and you are not asked again.**
97
+ To switch them off on a machine:
98
+
99
+ ```
100
+ dmonkey service set --deny-remotes # creates <agent home>/remotes-off
101
+ dmonkey service set --allow-remotes # removes it
102
+ ```
103
+
104
+ Off takes effect at once for new calls; within 3 seconds the agent disconnects and cancels calls
105
+ that were running or queued (what a call had already done is not undone). It stays off across
106
+ restarts until you switch it back. It changes no other permission (`dmonkey permissions show`).
107
+ If `config.json` is damaged, or the state directory cannot be read, remotes are treated as off and
108
+ `status` says why. A damaged file stays that way until you repair it, delete it, or run
109
+ `dmonkey service repair-config` (keeps it as a backup, starts from the defaults and leaves
110
+ remote connections switched off: deny again what you had denied, then run
111
+ `dmonkey service set --allow-remotes`).
112
+
113
+ A remote can set three configuration values (`fileReadLineLimit`, `fileWriteLineLimit`,
114
+ `telemetryEnabled`). It cannot set the allowed folders, the blocked commands or the default shell;
115
+ those are changed on the machine (`dmonkey remote --allow DIR`, or `set_config_value` in a local
116
+ `dmonkey mcp` session). An empty list of allowed folders refuses every path until you choose:
117
+ `dmonkey remote --allow <folder>` for only that folder, or `dmonkey remote --unrestricted` for
118
+ the whole disk.
119
+
120
+ Who can change it: no dashboard control, relay message or device tool does. One limit, stated
121
+ plainly: a remote you have given `run_commands` (on by default) runs commands as you, so it could
122
+ run this same command line. Switching off disconnects it first, so it would have had to prepare
123
+ that beforehand; `dmonkey permissions deny run_commands` rules it out.
124
+
125
+ Every command takes `--json`; that output is the interface Monkey Monitor uses
126
+ (`docs/adr/0009-autostart-and-persisted-remote-allow.md`, section C). Not yet run on a real
127
+ Windows or macOS machine.
128
+
129
+ ## Keep a program running with the agent (a model server on a VM)
130
+
131
+ The device owner can ask the agent to keep a long-running program alive. Declarations are made on
132
+ the machine. No relay message, dashboard control or file tool can change one, the agent's own
133
+ command (`dmonkey`, `python -m desktop_monkey`) is refused to remotes, and the relay can only ask
134
+ the agent to start a service that is already declared (the `dm_service_ensure` tool, gated by the
135
+ owner's `share_compute` grant; it takes a name and nothing else). One limit, stated plainly: a
136
+ remote holding `run_commands` runs commands as you, which is the same power as yours, and
137
+ revoking that grant later does not remove a service it may have declared. `dmonkey services list`
138
+ shows every declaration.
139
+
140
+ ```
141
+ dmonkey services add NAME [--env K=V ...] [--cwd DIR] -- COMMAND ARGS...
142
+ dmonkey services list # state, pid, restarts, last exit
143
+ dmonkey services restart NAME # also starts one the agent gave up on
144
+ dmonkey services remove NAME # stops it and forgets it
145
+ ```
146
+
147
+ The command is run without a shell (an argv list; newlines and NUL characters are refused). The
148
+ agent starts every declared service when it starts (`dmonkey remote`, autostart at login or boot,
149
+ `--unattended`), linked or not and whether or not remote connections are switched on. Each runs
150
+ in a session of its own and keeps running when the agent stops; an agent that starts again adopts
151
+ a process that still has the recorded pid, start time and command line instead of starting a
152
+ second copy. Output goes to `<agent home>/services/NAME.log` (5 MiB, then copied to `NAME.log.1`).
153
+ A program that exits is started again after 1 s, doubling to at most 5 min while it keeps exiting
154
+ within 30 s of starting; after 10 such exits in a row the agent gives up and says so in
155
+ `dmonkey services list`, `dmonkey service status --json` (`services`), the ping reply and the
156
+ mesh heartbeat. The memory guard does not count a declared service as part of the agent.
157
+
158
+ Limits: under the systemd user unit, `systemctl --user restart` of the agent kills everything in
159
+ the unit's cgroup, services included; they are started again when the agent comes back. A program
160
+ that forks into the background and exits at once looks like one that keeps failing.
161
+
162
+ **mesh-vm-2 (the dashboard chat's model on :8091).** The server there is
163
+ `/data/stageE_chat_server_v3.py`, started by `/data/server_ensure_v3.sh` with
164
+ `DM_RUN_THREADS=8 STAGEE_DTYPE=bfloat16`. That script has not been read from this repository, so
165
+ which command to declare depends on what it does:
166
+
167
+ * If `server_ensure_v3.sh` runs the server in the foreground (it ends in `exec python …` or simply
168
+ waits for it), declare the script:
169
+
170
+ ```
171
+ dmonkey services add stagee --env DM_RUN_THREADS=8 --env STAGEE_DTYPE=bfloat16 -- /bin/bash /data/server_ensure_v3.sh
172
+ ```
173
+
174
+ * If it starts the server in the background and exits (`nohup … &`, `setsid`, `disown`, or it
175
+ checks the port and returns), declare the server itself, with the interpreter and any further
176
+ environment that script sets:
177
+
178
+ ```
179
+ dmonkey services add stagee --env DM_RUN_THREADS=8 --env STAGEE_DTYPE=bfloat16 -- /data/dm-venv/bin/python /data/stageE_chat_server_v3.py
180
+ ```
181
+
182
+ (Check the interpreter path in the script; `/data/dm-venv/bin/python` is the expected one.)
183
+
184
+ `grep -nE 'nohup|setsid|disown|&\s*$|exec ' /data/server_ensure_v3.sh` tells which case applies.
185
+ Declare it once; the agent (PID 1 there runs it) starts it again after every container restart.
68
186
 
69
187
  ## Rules of the road
70
188
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@arcane-fly/desktop-monkey",
3
- "version": "0.1.7",
3
+ "version": "0.1.11",
4
4
  "description": "Desktop Commander-parity remote MCP plus a device mesh that pools compute, GPU, RAM and disk across your own machines. Name holder: the implementation is the Python package desktop-monkey; this npm package ships no JavaScript yet.",
5
5
  "repository": {
6
6
  "type": "git",