@arcane-fly/desktop-monkey
v0.1.11
Published
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.
Readme
Desktop Monkey
Your machines, one troop. A Desktop Commander–parity remote MCP plus a device mesh that pools compute, GPU, RAM and disk across the PCs and laptops you own.
Status: under construction — see docs/DONE-CONTRACT.json for the
machine-checkable list of what "finished" means and docs/STATUS.md for the live
done/asked count.
What it is
- Commander layer — 100% tool-surface and service parity with
Desktop Commander Remote MCP: every MCP tool, plus the
hosted pieces (device enrolment, tunnel, per-client OAuth, usage metering, tool-call log,
revoke/share, settings). Parity is tracked in
docs/parity/. - Troop mesh — concurrent coordination of several machines: primary + support, several
supports, rings and chains. Work is split so that no single machine has to carry the compute,
GPU memory, RAM or disk. See
docs/ARCHITECTURE.md. A sleeping machine is woken for waiting work, and a machine is kept awake, only when its owner switched that on for it (dmonkey power, or the dashboard's Devices tab; ADR 0008). - Hooks — an improved, typed, auditable hook engine (lessons from Claude Code, Codex and Cursor hooks) that also fires on mesh events.
- Monkey Monitor entry point — the local GTK app
(
monkey-projects/monkey-monitor) is the local front door; Desktop Monkey shares its colour tokens and logo.
Layout
One Python package, src/desktop_monkey/ (the earlier packages/ / services/ / apps/ split was
never built):
| Path | Purpose |
|---|---|
| src/desktop_monkey/protocol | MCP tool schemas + mesh wire messages |
| src/desktop_monkey/commander | Desktop Commander–parity MCP server |
| src/desktop_monkey/agent | Per-device daemon |
| src/desktop_monkey/mesh | Mesh scheduling, placement and pooling |
| src/desktop_monkey/relay | Control plane + tunnel (deployed on Railway) |
| src/desktop_monkey/hooks | Hook engine and adapters |
| src/desktop_monkey/learning | Learning experiments |
| src/desktop_monkey/monitor | Monkey Monitor integration |
| src/desktop_monkey/security | Security helpers |
| src/desktop_monkey/theme, theme/ | Colour + logo tokens shared with Monkey Monitor |
| tests/ | Test suite |
| deploy/ | targets.json (pinned IDs) + guard.py (deploy isolation check) |
| scripts/ | Dev and operator scripts (connect_relay_db.sh, …) |
| supabase/migrations/ | Mesh schema on supabase-monkey-one (public.mesh_*, RLS on) |
| docs/ | Vision, architecture, ADRs, parity matrix, research |
Live hub
The mesh relay is deployed on Railway as the central hub. This section lists its endpoints;
current health is in docs/STATUS.md.
| | |
|---|---|
| Public URL | https://relay-production-ef48.up.railway.app |
| Health | GET /health → {"status":"ok"} |
| MCP endpoint | POST /mcp (OAuth 2.1 bearer token, PKCE S256; 401 without token) |
| Device mesh tunnel | wss://relay-production-ef48.up.railway.app/tunnel |
| OAuth discovery | /.well-known/oauth-authorization-server (issuer = public URL) |
| JWKS | /.well-known/jwks.json (ES256) |
| Device enrolment | /device/start → /device/poll → /device/verify (device-code flow) |
| Device API | /api/devices (pause / resume / revoke) |
Devices and MCP clients connect to the public URL above; RELAY_PUBLIC_URL is set
on the Railway relay service so the OAuth issuer matches. The image is built from
the repo Dockerfile (pip install '.[relay,qig]'), which pins the relay extras the
platform builder would otherwise skip. The qig extra (qig-compute) is there because the relay
recomputes screened-QFI answers itself and refuses those jobs without it.
Start the agent at login, and the switch for remotes
Once a device is linked (dmonkey service link, or the first dmonkey remote), one command makes
it come back by itself after every restart and login, with no prompt:
dmonkey autostart enable # start at login, and now
dmonkey autostart status # installed / enabled / running / connected, and the exact command it runs
dmonkey autostart disable # stop it and remove the login entry| Platform | What enable installs |
|---|---|
| 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 |
| 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 |
| macOS | LaunchAgent com.github.arcane-fly.desktop-monkey.agent, restarted if it stops |
The login entry holds no credential: it runs dmonkey remote --foreground --unattended --server <relay>
and the agent reads its stored link itself. If the link is missing, unusable or was revoked, the
agent waits, disconnected, and status says so; it never asks for approval in a session nobody can
see. Only one agent runs per device: a second dmonkey remote exits with a line naming the first,
and enable stops one you started by hand.
Remote connections are allowed from the moment a device is linked and you are not asked again. To switch them off on a machine:
dmonkey service set --deny-remotes # creates <agent home>/remotes-off
dmonkey service set --allow-remotes # removes itOff takes effect at once for new calls; within 3 seconds the agent disconnects and cancels calls
that were running or queued (what a call had already done is not undone). It stays off across
restarts until you switch it back. It changes no other permission (dmonkey permissions show).
If config.json is damaged, or the state directory cannot be read, remotes are treated as off and
status says why. A damaged file stays that way until you repair it, delete it, or run
dmonkey service repair-config (keeps it as a backup, starts from the defaults and leaves
remote connections switched off: deny again what you had denied, then run
dmonkey service set --allow-remotes).
A remote can set three configuration values (fileReadLineLimit, fileWriteLineLimit,
telemetryEnabled). It cannot set the allowed folders, the blocked commands or the default shell;
those are changed on the machine (dmonkey remote --allow DIR, or set_config_value in a local
dmonkey mcp session). An empty list of allowed folders refuses every path until you choose:
dmonkey remote --allow <folder> for only that folder, or dmonkey remote --unrestricted for
the whole disk.
Who can change it: no dashboard control, relay message or device tool does. One limit, stated
plainly: a remote you have given run_commands (on by default) runs commands as you, so it could
run this same command line. Switching off disconnects it first, so it would have had to prepare
that beforehand; dmonkey permissions deny run_commands rules it out.
Every command takes --json; that output is the interface Monkey Monitor uses
(docs/adr/0009-autostart-and-persisted-remote-allow.md, section C). Not yet run on a real
Windows or macOS machine.
Keep a program running with the agent (a model server on a VM)
The device owner can ask the agent to keep a long-running program alive. Declarations are made on
the machine. No relay message, dashboard control or file tool can change one, the agent's own
command (dmonkey, python -m desktop_monkey) is refused to remotes, and the relay can only ask
the agent to start a service that is already declared (the dm_service_ensure tool, gated by the
owner's share_compute grant; it takes a name and nothing else). One limit, stated plainly: a
remote holding run_commands runs commands as you, which is the same power as yours, and
revoking that grant later does not remove a service it may have declared. dmonkey services list
shows every declaration.
dmonkey services add NAME [--env K=V ...] [--cwd DIR] -- COMMAND ARGS...
dmonkey services list # state, pid, restarts, last exit
dmonkey services restart NAME # also starts one the agent gave up on
dmonkey services remove NAME # stops it and forgets itThe command is run without a shell (an argv list; newlines and NUL characters are refused). The
agent starts every declared service when it starts (dmonkey remote, autostart at login or boot,
--unattended), linked or not and whether or not remote connections are switched on. Each runs
in a session of its own and keeps running when the agent stops; an agent that starts again adopts
a process that still has the recorded pid, start time and command line instead of starting a
second copy. Output goes to <agent home>/services/NAME.log (5 MiB, then copied to NAME.log.1).
A program that exits is started again after 1 s, doubling to at most 5 min while it keeps exiting
within 30 s of starting; after 10 such exits in a row the agent gives up and says so in
dmonkey services list, dmonkey service status --json (services), the ping reply and the
mesh heartbeat. The memory guard does not count a declared service as part of the agent.
Limits: under the systemd user unit, systemctl --user restart of the agent kills everything in
the unit's cgroup, services included; they are started again when the agent comes back. A program
that forks into the background and exits at once looks like one that keeps failing.
mesh-vm-2 (the dashboard chat's model on :8091). The server there is
/data/stageE_chat_server_v3.py, started by /data/server_ensure_v3.sh with
DM_RUN_THREADS=8 STAGEE_DTYPE=bfloat16. That script has not been read from this repository, so
which command to declare depends on what it does:
If
server_ensure_v3.shruns the server in the foreground (it ends inexec python …or simply waits for it), declare the script:dmonkey services add stagee --env DM_RUN_THREADS=8 --env STAGEE_DTYPE=bfloat16 -- /bin/bash /data/server_ensure_v3.shIf it starts the server in the background and exits (
nohup … &,setsid,disown, or it checks the port and returns), declare the server itself, with the interpreter and any further environment that script sets:dmonkey services add stagee --env DM_RUN_THREADS=8 --env STAGEE_DTYPE=bfloat16 -- /data/dm-venv/bin/python /data/stageE_chat_server_v3.py(Check the interpreter path in the script;
/data/dm-venv/bin/pythonis the expected one.)
grep -nE 'nohup|setsid|disown|&\s*$|exec ' /data/server_ensure_v3.sh tells which case applies.
Declare it once; the agent (PID 1 there runs it) starts it again after every container restart.
Rules of the road
Read AGENTS.md before touching anything — especially the deploy-isolation rules.
