📱 Remote Harness MCP — control any PC from Gemini Spark (App & Web)

An MCP server that turns Google Gemini from a chatbot into a full-fledged mobile agent. Type a task in the Gemini app on your phone — your PC, laptop or server executes it, and Gemini reports back with real results.

English | 🇷🇺 Русская версия

---

💡 The idea

Gemini in a browser or on a phone can talk, but it cannot do anything on your computer. Remote Harness MCP closes that gap. It is a free, open-source Model Context Protocol (MCP) server that you connect to Gemini Spark (gemini.google.com/customize/connectors or the Gemini mobile app) with a single link. After that, Gemini gets hands:

• runs shell commands, builds and tests code, manages git;
• reads, writes and edits files;
• searches the file system;
• starts long-running jobs and checks on them later;
• watches CPU, RAM and disk.

 📱 Gemini app / 🌐 gemini.google.com (Spark)
              │  MCP (SSE / Streamable HTTP)
              ▼
     ☁️  Gateway  racknerd-5a24bf9.merino-carob.ts.net   ← relay only, TLS
              │  outbound WebSocket tunnel (no open ports)
              ▼
   💻 Your PC · laptop · VPS · home server  →  executes the task

Result: your phone becomes a remote control for every machine you own — and Gemini is the agent that operates them.

---

🔥 What you can do with it

Just ask Gemini in plain language, from anywhere:

• “Check why my home server is slow and show the top processes”
• “Pull the latest changes in ~/projects/api, run the tests and tell me what failed”
• “Fix the typo in config.yaml and restart the service”
• “Start a full backup in the background and tell me when it’s done”
• “How much free disk space is left on my laptop?”
• “Turn on the phone’s torch, and tell me its battery level and signal”

No SSH client, no terminal on your phone, no VPN — only a chat.

---

✨ Why it works this way

---

🛠️ What Gemini can do on your machine (MCP tools)

26 tools. Every one of them runs on your machine under your own user account — the gateway only carries the calls.

Which calls ask for your confirmation

Gemini Spark decides whether to stop and ask “confirm this action?” from the MCP annotation hints each tool advertises (readOnlyHint, destructiveHint, idempotentHint, openWorldHint). A tool advertised with no hints at all is treated as destructive by the spec’s defaults — that is why a server that declares none gets a confirmation prompt on every single call. Here the hints are explicit:

A prompt is spent on a system change only: system_change, system_write and mesh_update install, remove, delete or replace something you cannot undo in one call. Everything else runs silently, the device branch included — a camera, a microphone or an SMS list installs and removes nothing, and what still refuses such a call is the node’s own switch (MESH_DEVICE, MESH_DEVICE_ACTIONS, MESH_DEVICE_PIM, MESH_READ_ONLY), which holds no matter what the client does. unshare is ordinary local work for the same reason: it stops a local server and removes a copy you can publish again in one call.

The mechanics matter if you also run the node in standalone mode: Gemini Spark skips its dialog only for a tool it sees as readOnlyHint: true, so the gateway advertises every non-system call that way — the shell and file twins because its classifier refuses the gated command classes, the device branch because the node refuses the call before any termux-* command runs. The node’s own tools/list keeps the literal hint instead (a camera is not a read), which is why a client connected straight to core/server.py may still ask.

Four classes are gated, and the gateway — not the hint — enforces them, because a hint is static per tool and cannot tell ls from apt install:

1. Installing or removing software — package managers, uninstallers, msiexec, dpkg/rpm, curl … | bash, iwr … | iex.
2. Deleting data — rm, Remove-Item, del, rd, shred, dd, mkfs, git clean -fd, docker rm/prune, truncate -s 0.
3. Running as root — sudo, doas, pkexec, runas, Start-Process -Verb RunAs.
4. System paths — /etc, /usr, /boot, /var/lib, /opt, /dev, C:\Windows, C:\Program Files, ProgramData, the registry. Reads of those paths (cat /etc/os-release, systemctl status) are not gated, and neither is ordinary work in your own directories.

bash_exec/run_job refuse such commands and tell the model to re-issue them as system_change; write_file/edit_file refuse a system path and point at system_write (which takes the exact content, so there is no shell quoting to get wrong). The gate is moved, not removed — inspection, builds, tests, config edits in your projects and the like still run without a dialog.

The tool surface and the confirmation policy live in gateway.py (annotations, INSTALL_COMMAND_PATTERNS / DELETE_COMMAND_PATTERNS, SYSTEM_PATH_RE, classify_command()) and in core/mcp_tools.py (TOOL_ANNOTATIONS for the node’s own surface, which also carries the device branch’s four tools); tests compare the two surfaces and pin the classifier, so a gated command cannot slip through.

[!NOTE] The classifier matches a verb at the start of a command segment (after sudo/env/timeout/powershell -Command prefixes), so echo "rm -rf /" or grep rm notes.txt still run, while curl … | bash counts as an install. It is a UX gate, not a sandbox: for hard guarantees independent of any prompt use the node’s own switches — MESH_READ_ONLY=1 and MESH_WRITE_ROOTS (core/agent.py).

Status and host information

Shell

Files

Search

Long-running work

Device (phone, laptop or server)

These four tools read and act on the device the node itself runs on. They are advertised on every node — a phone-only action on a laptop answers with available: false, the reason and, where one exists, the fix, instead of failing.

Example:

"Check the phone's battery and signal."
  → device_info(section="summary")

"Turn on the torch."
  → device_control(action="torch", on=true)

"Take a photo and share it with me."
  → device_capture(action="camera_photo")   # runs without a dialog
  → share_file(path=)

Device switches (operator)

Read from agent.env at startup (core/agent.py, applied in core/mcp_tools.py and core/device.py):

Publishing files and web pages

These four make something on your machine readable from the internet. The link is served by the gateway on the shared domain, so the node has to stay connected for it to work.

[!IMPORTANT] The random part of the path is the credential — anyone who has the link can read the file or browse the directory. Treat a share link like a password, and unshare it when you are done. Size limits: 32 MiB per file by default, 64 MiB ceiling via MESH_WEB_MAX_BYTES.

Agent behaviour

Keeping the node up to date

[!TIP] Nodes update themselves: a running agent checks for a newer release in the background (every 6 hours by default) and installs what it finds, and on Windows the RemoteHarnessMCPUpdater task checks once a day even when no agent is running. MESH_UPDATE_AUTO=0 switches that to “report only”. Details, environment variables and rollback: docs/UPDATES.md.

[!TIP] Gemini gives a single tool call roughly 30 seconds. For anything longer (builds, backups, downloads) the agent uses run_job and polls job_output, so tasks never get cut off.

---

🚀 Quick start — 2 minutes

1. Install the node on the PC you want to control

🐧 Linux / 🍎 macOS

curl -fsSL https://racknerd-5a24bf9.merino-carob.ts.net/install.sh | bash

📱 Android (Termux) — no root, works from F-Droid’s Termux

curl -fsSL https://racknerd-5a24bf9.merino-carob.ts.net/install.sh | bash

Autostart on a phone is a runit service plus the Termux:Boot app, and the node is named after the device model — see docs/TERMUX.md.

🪟 Windows (PowerShell)

irm https://racknerd-5a24bf9.merino-carob.ts.net/install.ps1 | iex

🪟 Windows — visual installer (from a clone or a release)

.\install-gui.cmd

A WinForms wizard that mirrors the console installer’s variants, switches language at runtime and shows the MCP link at the end — see docs/GUI_INSTALLER.md.

📦 Node.js (any OS)

npx remote-harness-mcp

The pre-rename name still works: npx gemini-computer-use is an alias package that depends on remote-harness-mcp and forwards every argument to the same CLI (see npm/gemini-computer-use).

🛠️ From source

git clone https://github.com/LevRa7/remote-harness-mcp.git
cd remote-harness-mcp
./install.sh --quick

At the end the installer prints your personal MCP link and copies it to the clipboard:

https://racknerd-5a24bf9.merino-carob.ts.net/sse?user=&token=

2. Connect it to Gemini Spark

1. Open gemini.google.com/customize/connectors in a browser or in the Gemini mobile app.
2. Click Add connector (or Settings ⚙️ → Connectors) and name it MyDevice.
3. Paste the link (Ctrl+V) into the Server URL field and click Connect.

3. Give it a task

“Show system_vitals and list the 5 biggest folders in my home directory.”

That’s it — Gemini is now an agent running on your machine. Repeat step 1 on other computers to control all of them from the same phone.

---

🖥️ Deployment modes

On Windows the same variants are available in the visual installer (.\install-gui.cmd); local standalone stays console-only there (.\install.ps1 -Mode standalone -Port 8096).

On Android/Termux the same ./install.sh variants work; autostart is a runit service plus the Termux:Boot app instead of systemd, and standalone stays reachable from that phone alone — see docs/TERMUX.md.

---

🪟 Windows installation

Windows already ships PowerShell 5.1, so there is nothing to prepare — no Python, no Node.js, no administrator rights. Both installers finish by putting the same MCP link on the clipboard.

Automatic dependencies and architecture

Nothing has to be prepared by hand first. Both installers obtain what they need, and if they cannot, they stop with an explicit message instead of writing an autostart entry that can never work.

websockets is the only external Python requirement: core/mcp_tools.py and core/server.py are standard library only. uv is fetched only when the cheaper paths have already failed.

The architecture decides which build is downloaded. The installer asks the OS, not the process, because a 32-bit PowerShell on 64-bit Windows reports x86 and hides the real value in PROCESSOR_ARCHITEW6432, and an emulated x64 process on ARM64 reports AMD64:

The interpreter that ends up pinned is the one that actually has websockets — which can be a venv or a uv-managed CPython, both deliberately outside PATH. install.ps1 -DryRun and install.sh --dry-run report the architecture without changing anything, and the visual installer shows it in its preflight.

Download the setup executable

The release also ships a single compiled installer, for machines where you would rather not clone or download anything else — RemoteHarnessMCP-Setup-.exe:

.\RemoteHarnessMCP-Setup-0.4.5.exe            # open the visual installer
.\RemoteHarnessMCP-Setup-0.4.5.exe -Lang ru   # start in Russian
.\RemoteHarnessMCP-Setup-0.4.5.exe -SelfTest  # headless self-check, prints JSON
.\RemoteHarnessMCP-Setup-0.4.5.exe --version  # print the version

It carries the wizard, install.ps1, core/ and install.sh inside itself, unpacks them to %LOCALAPPDATA%\RemoteHarnessMCP\setup\ (override with MESH_SETUP_DIR) and runs the wizard from there. It needs nothing but the .NET Framework and PowerShell that Windows already has, and it is built from this repository by .\build-installer-exe.ps1 — no SDK, no NuGet, no network.

It is not code-signed, so SmartScreen may ask for confirmation the first time you run it.

Visual installer

• Quick setup (recommended) — node name = PC name, shared gateway domain, Windows autostart. The one to pick on a home PC or laptop.
• Custom setup — your own node name, your own shared domain, optional token.
• Remote over SSH — copy the node code to a Linux host and run install.sh there. Needs the Windows OpenSSH Client feature and key-based authentication; interactive password prompts are not supported.

The first screen runs install.ps1 -DryRun and reports what it found — Python, websockets, the resolved gateway domain, the config directory, the autostart path — without changing anything. Before starting, the window shows the exact command it will run; during the run it streams the installer output; at the end it shows the MCP link with a copy button, the three-step Gemini instructions and the paths it created.

Full details, screenshots and the SSH notes: docs/GUI_INSTALLER.md.

What a Windows installation creates

Language

The visual installer starts in the language of your Windows language settings — the display language and the preferred-languages list are read from the registry — and falls back to English. -Lang ru / -Lang en overrides the detection. The switch in the window header changes every label immediately.

Troubleshooting

• “No gateway domain configured” — this copy was not published with a domain. Pass one: use Custom setup in the wizard, or .\install.ps1 -Gateway , or set MESH_PUBLIC_URL.
• Registration fails — the installer stops before writing anything when the gateway cannot be reached. Check that the domain resolves, then retry with an explicit -Gateway.
• python opens the Microsoft Store — that is the App Execution Alias, not an interpreter. Both installers resolve a real python.exe by full path and ignore the alias; the wizard never pins an alias into the autostart entry.
• The node does not come back after a reboot — run .\ops\doctor.ps1: it prints the autostart interpreter, the heartbeat age, the last agent.log lines (including a torn final line) and the gateway’s own view of this node. .\ops\windows\agent-watchdog.ps1 performs that check once and restarts the agent; the scheduled task RemoteHarnessMCPWatchdog runs it every five minutes, so a dead agent comes back on its own.

Standalone on Windows

The wizard does not offer it; use the console installer:

.\install.ps1 -Mode standalone -Port 8096

That starts a local-only FastMCP server at http://localhost:8096/sse and puts that URL on the clipboard.

---

📱 Android installation (Termux)

The same install.sh installs a node on an unrooted phone or tablet, and the phone then shows up in Gemini Spark like any other machine. Full guide: docs/TERMUX.md.

# 1. Termux from F-Droid (not Google Play); optionally Termux:Boot and Termux:API
pkg update -y
# 2. the usual one-liner
curl -fsSL https://racknerd-5a24bf9.merino-carob.ts.net/install.sh | bash

What a phone changes, and how the installer handles it:

[!IMPORTANT] Two Android-side switches are yours to flip: install Termux:Boot and open it once, and set battery optimisation to Unrestricted for Termux. Without them Android unloads the node with the screen off.

The phone must also be able to resolve the gateway name. A gateway that lives on a private network (Tailscale, a VPN, a DNS override on your laptop) resolves there and nowhere else — mobile data resolves nothing private. Put the phone on that network, or give the gateway a publicly resolvable domain; the installer detects a name it cannot resolve and says so before writing anything: see docs/TERMUX.md.

sv status rhm-agent                       # is it up?
sv restart rhm-agent                      # restart now
tail -f $PREFIX/var/log/sv/rhm-agent/current

--mode=standalone also works, but it serves 127.0.0.1 only — reachable from inside that phone alone. Use the default tunnel mode to drive the phone from Gemini.

---

🔄 Automatic updates

A node installs itself from a GitHub release and then keeps itself current the same way. You do not re-install anything by hand, and nothing unverified is installed.

• It checks by itself. A running agent asks the GitHub Releases API every 6 hours (MESH_UPDATE_CHECK_INTERVAL), compares the tag with the version in core/version.py and installs what it finds. On Windows the daily RemoteHarnessMCPUpdater task does the same for a machine whose agent is not running. MESH_UPDATE_AUTO=0 turns installing off and keeps reporting.
• It verifies before it installs. The payload is downloaded, its SHA-256 is compared with the published checksum, and only then are core/, skills/ and ops/ replaced. No checksum, no update.
• It can always go back. The replaced directories are saved under %USERPROFILE%\.config\remote-harness-mcp\backups\-\, and an update interrupted by a kill or a power cut is rolled back automatically on the next start.
• The node comes back new. The agent is restarted through whatever supervises it (the watchdog task on Windows, systemctl --user restart rhm-agent.service, launchctl kickstart -k) — or started directly when nothing supervises it.

By hand, any time:

remote-harness-mcp update -Check      # is a newer release published?
remote-harness-mcp update             # install it now and restart
remote-harness-mcp update -Check -Json

From Gemini: ask the node to run mesh_update (status, then check, then apply).

The state of the last check is in the heartbeat, so ops/doctor.ps1 shows it, and the full history is in %USERPROFILE%\.config\remote-harness-mcp\update.log. Configuration, exit codes, rollback and troubleshooting: docs/UPDATES.md.

---

🔗 One shared domain (canonical URL contract)

A node is never addressed by its own hostname. The gateway publishes a single shared domain, and the node name travels as a query parameter:

Why: every extra hostname would need its own DNS record and its own SAN in the TLS certificate. A node whose name is missing from the certificate fails the TLS handshake, and the Gemini client then reports an opaque “cannot connect to host”. With one shared domain the certificate covers every node forever, and adding a node is only a registration call.

• The shared domain defaults to smart-server.online; override it with ./install.sh --domain= (node side) or MESH_PUBLIC_URL (gateway side).
• Legacy per-device subdomain URLs still resolve for backwards compatibility and log a deprecation warning; set MESH_LEGACY_SUBDOMAIN=0 on the gateway to reject them outright.
• The installer now records the domain it resolved in the domain file, so the node’s share links, its tunnel and the gateway all name the same host: MESH_PUBLIC_URL=https:// in domain.env, written in both install branches (standalone, and cloud-gateway/tunnel right after agent.env). The value is normalised first, the __MESH_DOMAIN__ placeholder and an empty value are never written, the write is skipped when the file already names that host, and a file that cannot be written is not fatal — the installer prints the exact command to run by hand. The built-in default is never recorded at all: it is a fallback, not a configuration, and pinning it would stop core/domain.py from consulting the legacy MESH_GATEWAY at all, so a later change in agent.env would be silently ignored — nothing is lost, because with no file that same value is already the resolver’s last fallback. --dry-run reports the file and the value it would write — including not written (the built-in default is a fallback, not a configuration) — and still changes nothing on disk.
• Why this matters: share links are built by core/domain.py, whose chain is MESH_PUBLIC_URL → AGY_PUBLIC_BASE_URL → the domain file → the built-in default, and which deliberately never reads the legacy MESH_GATEWAY that agent.env carries (only gateway_host(), the tunnel host, does). A node installed the normal way — agent.env with MESH_GATEWAY/MESH_USER/MESH_TOKEN and no domain file — therefore dialled the right gateway while minting links on the built-in default. On an already-installed node, re-run the installer or write the one line by hand: mkdir -p ~/.config/remote-harness-mcp && echo 'MESH_PUBLIC_URL=https://' > ~/.config/remote-harness-mcp/domain.env, or the same with sudo tee /etc/remote-harness-mcp/domain.env on Linux. Existing share links keep working; new ones use the configured domain.
• MESH_DOMAIN_FILE only overrides the path, and it belongs to the node’s own configuration rather than to the installer invocation: keep it in agent.env (every MESH_* key there is exported to the node), or the domain is written into a file the node never reads. The installer creates the parent directory of whichever file is in effect. Over --ssh= the domain resolved here is handed to the remote install.sh as --domain=, so the target records that host instead of re-resolving it (a repository copy still carrying the __MESH_DOMAIN__ placeholder would otherwise fall back to the built-in default).

---

🔒 Security

• Token-gated endpoints — every request must carry the node’s secret token.
• Outbound-only tunnel — nodes never listen on public ports; the agent dials out to the gateway.
• Gateway is a relay — it terminates TLS and forwards calls; commands run only on your node.
• Unprivileged by default — the agent runs in user space, without root.

[!WARNING] Whoever has your MCP link can run commands on that machine. Treat it like a password: don’t publish it, and reinstall the node to rotate the token if it leaks.

---

🚢 Self-hosting the gateway

The gateway is a single host serving every node. Publish it only through the deploy script, so the running gateway, the served installers and the node bootstrap payload cannot drift apart:

MESH_GATEWAY_SSH=root@ ./deploy_gateway.sh              # deploy
MESH_GATEWAY_SSH=root@ ./deploy_gateway.sh --dry-run    # preview
MESH_GATEWAY_SSH=root@ MESH_GATEWAY_SSH_PASS_FILE=~/.ssh/gw-pass \
    ./deploy_gateway.sh                                            # password auth

It verifies every upload with an sha256 manifest on the host, takes a timestamped backup, installs with the right owner, restarts the service and finishes with a public health check. Nothing is installed if verification fails.

[!TIP] One place for the domain. MESH_PUBLIC_URL in domain.env (/etc/remote-harness-mcp/domain.env on Linux, %USERPROFILE%\.config\remote-harness-mcp\domain.env on Windows) is the only setting that names it: the node, the gateway, the installers, the public file links and the nginx vhosts all resolve it through core/domain.py. Switching domains is one value plus ops/nginx/render-domain.sh --apply — see docs/DOMAIN.md.

[!IMPORTANT] install.ps1 encoding — one file, two representations. The repository copy is UTF-8 with a BOM: Windows PowerShell 5.1 decodes a BOM-less script with the ANSI code page, the Russian strings then turn into smart quotes and the parser rejects the whole file, so .\install.ps1 from a clone would not run. The copy the gateway serves is written without the BOM by deploy_gateway.sh, because irm … | iex receives the BOM as part of the first token and param(...) then stops being the first statement. nginx declares charset utf-8 for that location, so the BOM-less copy still decodes correctly. Please keep both properties when editing the file.

TLS certificate policy — one name, no per-device SANs. The certificate must cover the shared domain only; a node is selected by ?user=, never by a hostname:

# what the certificate currently covers
sudo certbot certificates | grep -A1 'Certificate Name: smart-server.online'

# canonical renewal check (staging, does not touch the live certificate)
sudo certbot renew --dry-run --cert-name smart-server.online

Legacy per-device SANs may still be present from before this contract. They are harmless and keep old bookmarked URLs working; drop them at the next renewal once no client uses subdomain URLs any more (see the domains = line in /etc/letsencrypt/renewal/.conf, or re-issue with a single -d).

---

📄 License

MIT — see LICENSE.