Muse Link

Connect Muse or another MCP-capable agent to the tools on your signed-in Windows PC over SSH. Keep the browser and desktop processes in the interactive session; expose their tools through a small authenticated loopback broker.

This is the connection layer extracted from a working Muse/OpenClaw setup. It is a separate package from SideScreen, which supplies the optional virtual display and scoped desktop input.

flowchart LR
  Agent["Muse / MCP agent"] -->|SSH stdio| Proxy["Muse Link proxy"]
  Proxy -->|authenticated loopback| Broker["Broker in signed-in Windows session"]
  Broker --> Chrome["Chrome extension / existing tabs"]
  Broker --> External["External Patchright or other MCP tools"]
  Broker --> SideScreen["SideScreen / optional CUA"]
  Broker --> Desktop["Optional installed desktop adapter"]

What is included

• CLI and MCP stdio proxy, including an agent-side Python SSH helper.

• A loopback-only broker with per-run credentials, protected local state, and serialized engine calls.

• A Chrome adapter using pinned Playwright MCP in extension mode.

• The four scoped SideScreen tools: status, windows, observe, and act.

• Configurable external MCP engines and the existing desktop JSON adapter protocol.

• Windows sign-in startup, restart supervision, pause/resume scripts, and transport tests.

No keys, hostnames, personal endpoints, browser profiles, OpenClaw workspace files, or external driver binaries are included. Muse Link does not install an SSH server, configure firewall rules, or create a public tunnel. You need an existing SSH connection; a mutually connected Tailscale network is one option.

Related MCP server: windows-host-mcp

Install on Windows

Use Node.js 22 or later and Git. In the signed-in desktop's PowerShell:

$package = Join-Path $env:LOCALAPPDATA 'MuseLinkPackage'
git clone https://github.com/gitWRLD999/muse-link.git $package
Set-Location -LiteralPath $package
npm ci
node .\bin\muse-link.mjs init
node .\bin\muse-link.mjs serve

The config defaults to %LOCALAPPDATA%\MuseLink\config.json, with credentials in its state directory and CLI screenshots in artifacts. Ctrl+C stops a manually started broker. A Windows broker providing desktop/browser adapters must run in a signed-in interactive session, rather than an SSH service session.

You can also install the v1.0.0 npm package archive:

npm install -g https://github.com/gitWRLD999/muse-link/releases/download/v1.0.0/gitwrld999-muse-link-1.0.0.tgz
muse-link init
muse-link serve

The package is distributed on GitHub Releases; it has not been published to the npm registry. Source checkout is convenient when using the startup scripts.

Use your regular Chrome account

Install the Playwright MCP Bridge extension in the Chrome profile you want the agent to use. Chrome asks you to select a tab when attaching. The chrome engine uses extension mode and does not copy your profile or launch Chrome with a debugging port. See Playwright MCP's browser extension instructions.

In config.json, set chrome.profile to a profile directory name such as Default or Profile 1 if necessary. This is a local setting. Keep browser consent and credentials on the PC.

node .\bin\muse-link.mjs status
node .\bin\muse-link.mjs chrome list

Connect Muse or another agent

Configure SSH key authentication for the Windows account and verify the server's host-key fingerprint through a trusted channel before adding it to the agent's known_hosts. The SSH helper requires strict host-key checking and refuses password prompts. Use your existing working SSH setup; no SSH passwords or private keys belong in this repo.

Add an SSH alias such as agent-pc to the agent's SSH config, pointing to the reachable PC and the correct account/key. Check connectivity first:

ssh -T -o BatchMode=yes -o StrictHostKeyChecking=yes agent-pc whoami

For a command-line agent, Python 3 and OpenSSH are enough on the agent side. Replace the remote script path with the installed Windows path:

python3 scripts/muse-ssh.py --host agent-pc \
  --remote-script 'C:/Tools/muse-link/bin/muse-link.mjs' status
python3 scripts/muse-ssh.py --host agent-pc \
  --remote-script 'C:/Tools/muse-link/bin/muse-link.mjs' chrome list

To use MCP, copy examples/mcp-ssh.json into your MCP client's configuration and replace the alias and remote script path. Each configured server forwards one engine's tools. This works with a client that can launch an SSH stdio transport; it does not add a new native computer-use capability to a hosted chat interface.

The Python helper also supports MCP streaming:

The helper's remote command assumes Windows OpenSSH's default cmd.exe shell. If your SSH server uses a custom shell, use an appropriate direct SSH command in the MCP config instead. Remote paths containing shell expansion/operator characters are refused by the helper.

python3 scripts/muse-ssh.py --host agent-pc \
  --remote-script 'C:/Tools/muse-link/bin/muse-link.mjs' --mcp sidescreen

All MCP protocol output goes to stdout; broker/engine diagnostics go to stderr. CLI screenshots are saved on the PC and returned as paths for retrieval with scp. MCP screenshots remain image content.

Keep it running after sign-in

Once manual access works, stop the manually started broker with Ctrl+C and install the startup task from the package directory:

.\scripts\Install-Startup.ps1 -StartNow

This registers a task named Muse Link for the current user's interactive sign-in. The supervisor restarts the broker if it exits and retries after ten seconds. It waits while another process owns the configured port and never replaces that process. Keep the package directory and Node installation in place. Browser engines reconnect lazily after restart; Chrome may require tab selection again.

This is durable across reboot after the user signs in. It does not keep a desktop available through sign-out or provide a VM. Network reachability and browser consent must still be available.

.\scripts\Pause-Muse-Link.ps1
.\scripts\Resume-Muse-Link.ps1

Pause remains in effect across supervisor restarts. To uninstall startup, pause first, then run:

Unregister-ScheduledTask -TaskName 'Muse Link' -Confirm:$false

These scripts use the default home or -HomeDirectory. Install-Startup.ps1 records the current Node and package paths, refuses to overwrite an existing task, and does not change the legacy Muse OpenClaw Tools task. Supervisors read the specified home's config; temporary shell environment overrides are deliberately cleared.

External engines and SideScreen

examples/external-engines.json shows external Patchright and desktop adapters. Replace all example paths with your installed tools; these engines are not bundled or enabled by default.

The default SideScreen directory is %LOCALAPPDATA%\SideScreenTools; SIDESCREEN_HOME can override it. Install SideScreen and its optional CUA integration separately. Discover the display and window handles using status/windows, then observe before each action. SideScreen enforces target containment and observation expiry; Windows focus is still shared, and supported background input is not universal desktop isolation. The unscoped legacy desktop adapter can steal focus.

For the desktop protocol, requests look like {"action":"/windows","arguments":{}}; replies look like {"ok":true,"result":...}. /screenshot may return result.png_base64. Only the published action allowlist is exposed. External MCP engine schemas pass through unchanged. Installed OpenClaw tools retain their own dependencies and permissions.

The config is trusted local code-launch configuration, not an agent-facing arbitrary shell tool. Change it only on the PC. Restart the broker to reload it. Runtime RPC accepts only status, tool listing, and tool calls on configured engines.

Use alongside an already working Muse broker

You do not have to migrate or restart the working connection to try the new CLI/proxy. Point this shell at the existing broker's state directory and port:

$env:MUSE_LINK_STATE_DIR = 'C:\Path\To\Existing\Muse-OpenClaw\state'
$env:MUSE_LINK_PORT = '18921'
node .\bin\muse-link.mjs status
node .\bin\muse-link.mjs mcp chrome

These overrides let the proxy talk to the existing broker, including its installed Patchright and desktop tools. They do not start another broker. For a persistent SSH proxy using the legacy broker, set an absolute stateDir and matching port in Muse Link's local config for the same Windows account. Do not point a new serve instance at a live broker's state directory.

For a later migration, configure the external engines first, pause the old supervisor using its own scripts, then start Muse Link and verify status/tools before enabling its startup task. The two brokers should use separate state directories and different ports if run simultaneously.

Configuration and boundaries

MUSE_LINK_HOME chooses the config/data home. MUSE_LINK_CONFIG chooses a config file. MUSE_LINK_PORT overrides port. MUSE_LINK_STATE_DIR overrides stateDir. The default port is 18921 and the broker always binds 127.0.0.1. Non-Windows defaults use ~/.local/state/muse-link for transport development and external MCP engines; the bundled desktop adapters target Windows.

The broker rejects browser Origin headers, unexpected Host headers, incorrect bearer tokens, malformed JSON, and requests larger than 1 MiB. It rotates credentials only after successfully binding its port. State has restricted Windows ACLs or owner-only directory/file modes on other platforms. Successful calls can still have a tool-specific refusal or error; inspect returned results. Actions are never retried automatically after a timeout or unknown outcome.

SSH provides network transport and account authorization. A user or process already running as that Windows account can access the broker token. Engine calls are serialized across connections; status can be read while a call is busy. Serialization does not reserve the PC for an agent or isolate it from human input. Engine startup may launch processes, so only configure engines you intend to expose.

Development

npm ci
npm test
python -m unittest discover -s test -p 'test_*.py'
npm pack

CI runs transport/authentication tests on Windows and Linux with Node 22 and 24. Tests use a mock MCP engine and never send desktop input. Optional engines require separate live validation on the machine where they are installed. See NOTICE.md for source and dependency attribution.