📱 Remote Harness MCP — control any PC from Gemini (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.

Related MCP server: TerminalMCP

🔥 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.

📸 In action

Three exchanges from one chat, each answered by a different machine on the other side of the bridge. The phone never opened a terminal.

The laptop describes itself — "@Rem Matebook-deb, give me the system and hardware specs":

The phone reports its own battery, radio and VPN — "@Rem Phone, check". The SSID and both addresses are mosaicked; everything else came from device_info:

The desktop is photographed, published and read back — "take a screenshot of @RemMatebook-deb", then "describe what is running on the screens":

Every answer was produced by system_vitals, device_info, device_capture and share_file running on the node itself — the model only ever saw tool results.

✨ 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.

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=<the path it returned>)

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.

Agent behaviour

Keeping the node up to date

🚀 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=<your-node-name>&token=<your_secret_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-<version>.exe:

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

It carries the wizard, install.ps1, core/ and install.sh inside itself, unpacks them to %LOCALAPPDATA%\RemoteHarnessMCP\setup\<version> (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 <shared-domain>, 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:

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\<version>-<timestamp>\, 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=<shared-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://<shared-domain> 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://<domain>' > ~/.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=<host> 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

• Two credentials per node — the device token opens the tunnel and is accepted only in an Authorization: Bearer header; the link key (lk_…) is the only credential allowed in a URL. The device token in a query string is rejected with HTTP 401.

• Link keys rotate — POST /v1/devices/<node>/rotate issues a new link key and kills the old URL; POST /v1/devices/<node>/revoke removes the node. Neither needs a reinstall.

• The device token rotates too — no reinstall. From the node's payload directory run python3 -m core.rekey (Windows: cd $env:USERPROFILE\.remote-harness-mcp; python -m core.rekey). It asks the gateway for a new token, writes it into agent.env, the launchd plist on macOS and the Startup launcher on Windows, restarts the supervisor (systemd / launchd / Scheduled Task / runit) and waits for the node to report online. The previous token keeps working until the node connects with the new one, so a failed restart restores the old token instead of locking the machine out. POST /v1/devices/<node>/rotate-token/finish retires it immediately when the old token is known to be in someone else's hands. The remote-harness-mcp rotate shorthand is the same command through the npm CLI.

• Enrolment — /api/register refuses to hand a token to a request that only knows a name or a MAC address; possession of the device token is required to reuse a registration. Set MESH_REGISTER_MODE=pair (with MESH_ADMIN_TOKEN) to replace self-registration entirely with the pairing flow: POST /v1/devices/pair → approve the code → collect the credentials.

• 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.

🚢 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@<gateway-ip> ./deploy_gateway.sh              # deploy
MESH_GATEWAY_SSH=root@<gateway-ip> ./deploy_gateway.sh --dry-run    # preview
MESH_GATEWAY_SSH=root@<gateway-ip> 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.

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/<name>.conf, or re-issue with a single -d).

📄 License

MIT — see LICENSE.