Remote Assist Tool

English | 简体中文

A command-line remote assistance tool: it sets up a secure tunnel through a relay server (or LAN direct connection / NAT-traversing P2P). It supports classic SSH remote assistance, and also lets a local AI agent debug a remote machine directly through an MCP tool channel — Claude Code, Codex, Doubao, or any other agent that supports MCP.

Features

• Two assistance channels: a classic SSH tunnel; and an MCP tool channel (12 remote tools, including file upload/download) that works with any MCP-capable AI agent.
• Three connection modes: public relay; LAN direct connection via an in-process relay (--standalone); NAT-traversing P2P direct connection (STUN hole punching, automatically falling back to the relay on failure).
• Layered encryption: TLS on the relay link; the MCP tool channel additionally uses XChaCha20-Poly1305 AEAD with a key derived from the assist code, protecting against network paths outside the relay. The relay itself is a trust boundary (the assist code is generated by it, see Security Features below), so use a relay you deploy yourself.
• Guardrails: exec command deny/allow lists; an optional --root that confines the file tools to a subtree (protection against slips, not a security boundary — exec is not bound by it).
• Relay hardening: connection rate limiting (global + per IP), read/write timeouts, and a per-message size cap, to resist resource-exhaustion DoS / slowloris.

Quick Start

One-line install of remote

The script downloads the client for your current OS and architecture from the latest official GitHub Release and installs it as ~/.local/bin/remote (remote.exe in Git Bash / MSYS2 / Cygwin on Windows):

curl -fsSL https://raw.githubusercontent.com/kegechen/remote-assist-tool/master/install.sh | sh

You can also use wget, or set the install directory with REMOTE_INSTALL_DIR:

wget -qO- https://raw.githubusercontent.com/kegechen/remote-assist-tool/master/install.sh | sh
REMOTE_INSTALL_DIR=/usr/local/bin sh install.sh

If remote is already installed, the script compares its remote --version with the latest Release tag: it skips the download when they match and updates in place otherwise. Either way it then starts remote (no arguments = share mode). Arguments after sh -s -- are passed through, and REMOTE_INSTALL_NO_RUN=1 installs/updates without starting it:

curl -fsSL https://raw.githubusercontent.com/kegechen/remote-assist-tool/master/install.sh | sh -s -- share --standalone
curl -fsSL https://raw.githubusercontent.com/kegechen/remote-assist-tool/master/install.sh | REMOTE_INSTALL_NO_RUN=1 sh

When there is no terminal (CI, unattended provisioning) the script only installs and does not start remote.

Supports amd64 and arm64 on Linux, macOS and Windows (Git Bash / MSYS2 / Cygwin); on Linux/macOS the downloaded file is made executable automatically; on Windows, if the curl / wget download fails, the script falls back to the system PowerShell.

Before installing, the script fetches the SHA256SUMS of the same Release and verifies the downloaded binary; on mismatch it aborts and leaves no files behind. If the checksum list cannot be fetched it likewise aborts — to bypass this, explicitly set REMOTE_INSTALL_SKIP_CHECKSUM=1.

If you download manually, you can verify it yourself:

curl -fLO https://github.com/kegechen/remote-assist-tool/releases/latest/download/SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing   # macOS: shasum -a 256 -c SHA256SUMS --ignore-missing

Note that SHA256SUMS and the binary come from the same Release over the same HTTPS connection, so it protects against "what you downloaded is incomplete or was swapped in transit", not "the Release itself was replaced" — the latter requires signatures, which this project does not provide yet.

Build

Use the scripts in the repository; artifacts go to bin/ (.exe on Windows):

# Windows
scripts\build.bat
# Linux / macOS
./scripts/build.sh
# Cross-compile Linux artifacts on Windows
scripts\build-linux.bat

All artifacts carry a platform suffix (<component>-<os>-<arch>), so you can tell at a glance which platform a binary is for, and it will not collide with anything else on your PATH:

| Artifact | Description | |---|---| | bin/remote-assist-cli-windows-amd64.exe | The client: both the share and help roles, and also the MCP entry point | | bin/remote-assist-webui-windows-amd64.exe | Browser console (looks for the cli above in the same directory / bin/) | | bin/remote-assist-relay-windows-amd64.exe | Relay server | | bin/remote-assist-{cli,relay}-linux-{amd64,arm64} | Produced by cross-compiling with scripts/build-linux.bat |

Windows artifacts embed product information (product name / description / version are visible in the file's Properties), generated by goversioninfo from git describe. The tool is pinned into go.mod via tools.go: after one go mod download, you can build offline and don't need network access every time.

Tip: for a pure compile check use go build ./... (produces no files); to get artifacts, always pass -o bin/ or use the scripts above, so executables don't end up scattered in the repository root.

Upgrading share from the Web UI

After connecting, the Web UI compares the versions of help and share; when share is confirmed to be older, an upgrade prompt appears at the top. After you pick the CLI binary matching the remote OS and architecture, the backend performs a "make before break" handover:

1. Through the old channel it probes the PID, the original executable path, the OS and the architecture. Before uploading it checks the candidate file's ELF/PE machine; only after confirming that Linux/Windows and amd64/arm64 both match does it upload in chunks, and then it runs --version remotely to verify.
2. It reuses the old share's parameters and starts new with an isolated HOME (a separate ClientID) and a fixed --code-file. When upgrading the default instance, the isolated HOME does not change its single-instance lock: while old holds the lock, new queues up to take over, so starting the default share again during the handover still fails immediately.
3. Still through the old channel, it reads the new code, actively connects to new and checks the version.
4. On Linux, after new is verified, the original file is atomically replaced and old is then terminated by PID. On Windows, the running old is first renamed to a backup name so the candidate file can take over the original path, and then new is started; after new is verified, old is terminated by PID and the backup is deleted; if the switch fails, the original file is restored through the old channel.

If any step before the switch fails, old is not terminated; if connecting to new fails, it tries to reconnect to old automatically. Currently only Linux/Windows amd64/arm64 shares using an external relay are supported; --standalone / --no-auth are rejected. If --allow-exec is configured, the sh/powershell.exe, mkdir, chmod, kill needed for the upgrade, as well as the candidate binary, must also be allowed to run. After the original path is replaced, existing systemd / startup configurations need no file-name changes; the temporary takeover process keeps using the isolated ClientID, and the next normal start from the original path restores the standard HOME/ClientID.

Usage 1: Classic SSH remote assistance (via relay)

On the machine being assisted (sharing its local SSH):

remote share --server relay.example.com:8443

--server is not required: if omitted, the built-in public relay 23.95.78.14:8443 is used; only fill in your own address when connecting to a self-hosted relay.

The program displays an assist code, for example:

协助码已生成: ABCD-EFGHIJ
有效期至: 2026-02-28 18:30:00
等待协助端连接...

By default only one share is allowed per user. To additionally share a different SSH service or use a different tool policy, explicitly create a separate instance:

remote share --ssh 127.0.0.1:22 --server relay.example.com:8443
remote share --new-instance --ssh 127.0.0.1:2222 --server relay.example.com:8443

Starting the default instance a second time fails immediately and does not disconnect the instance that is already running. Each use of --new-instance creates an independent assist code; while the code is valid, that process keeps the same code when its network drops and reconnects, but after the process exits, starting it again generates a new code. When connecting to an external relay, share only makes outbound connections and does not need a local listening port per instance; the --ssh port is just the local SSH service being proxied. In standalone mode each instance embeds a relay, so you must also set a different --standalone-listen port for each one.

On the helper side (connect with the assist code; MCP mode is the default, add --legacy-ssh for a traditional SSH tunnel):

remote help --server relay.example.com:8443 --code ABCD-EFGHIJ --legacy-ssh
# You can also omit --server and use the built-in public relay directly
# Then in another terminal:
ssh -p 2222 user@127.0.0.1

--insecure defaults to true: the built-in / standalone relays use self-signed certificates, so it works out of the box. When connecting to a relay with a certificate from a trusted CA, explicitly pass --insecure=false to enable certificate verification.

Skipping verification does not mean there is no authentication: the first time you connect to a relay address, its certificate fingerprint is recorded in ~/.remote_assist_known_hosts (TOFU, like SSH's known_hosts), and a later fingerprint change is refused. If the relay really did change its certificate, add --trust-new-cert to trust it again, or delete the corresponding line in that file. Connections to localhost / 127.0.0.1 are not pinned (loopback has no man-in-the-middle to defend against, and multiple relays on one machine would share the same address key).

Usage 2: LAN direct connection (standalone, no external server)

The machine being assisted starts a self-signed TLS relay inside its own process and listens on the LAN; the help side connects directly to that machine, with no dependence on any external server:

remote share --standalone --standalone-listen :8443

The console prints the command for the help side (the LAN IP is detected automatically):

================ standalone (LAN) mode ================
Relay (TLS, self-signed) listening at: 192.168.1.23:8443 (LAN reachable)
Help side connects exactly like a normal relay (no --plain needed):
    remote help --server 192.168.1.23:8443 --code <code> --p2p disabled
=======================================================

The standalone self-signed certificate only covers localhost; in LAN scenarios keep the default --insecure=true (do not use --insecure=false, which fails because the certificate's SAN does not include the LAN IP).

The certificate is stored in ~/.remote_assist_standalone_certs/ and reused across launches (regenerated only when close to expiry), so that the help side's fingerprint pinning keeps matching. Deleting this directory switches to a new certificate, after which existing help sides need --trust-new-cert.

Usage 3: AI agent remote debugging via MCP

Let a local AI agent debug the remote machine directly, with no openssh-server needed on the remote side. remote help --mcp-stdio is a standard stdio MCP server, and any MCP-capable agent such as Claude Code, Codex or Doubao can plug into it. For first-time setup, you can simply hand MCP_SETUP.md (Chinese) to your AI assistant and let it complete the remote download and the remote-debug MCP configuration automaticall