Connect a VM

An Escanor machine is a server running the Remote Harness agent. It connects outward to your hub and appears in the phone app's Machines list, ready to run Claude Code sessions. Desktop computers use a separate phone pairing flow.

Prerequisites#

• A Linux server you can administer, with Node.js 20+, git, npm and systemd.
• An interactive terminal and sudo permission to install the service.
• Outbound access to GitHub/npm, your hub's WebSocket URL, and services used by sessions.
• A dedicated project directory and an unprivileged OS account.
• Claude Code credentials: log in on the server or provide your own Anthropic API key when asked. That account's limits still apply.

node --version
git --version
npm --version
systemctl --version

The installer refuses Node below 20. It does not provision a VM. The outbound agent connection needs no inbound port.

Get your connection details#

In the phone app, sign in, open Machines and choose Connect a machine. Copy your own command with the hub URL and token. Keep that token out of support messages, chats and repositories.

The bootstrap is in the Remote Harness repository. Download and review it before running:

curl -fsSL \
  https://raw.githubusercontent.com/yashmishra2006/remote-harness-for-vms/main/packages/agent/bootstrap.sh \
  -o bootstrap.sh
less bootstrap.sh

Run with your own values; these placeholders are intentionally invalid:

HUB_URL='wss://YOUR_HUB_HOST/agent' \
HUB_TOKEN='YOUR_AGENT_TOKEN' \
bash bootstrap.sh

It clones or updates the repository, then runs the installer. Set REMOTE_HARNESS_REF to a reviewed tag/commit to pin the checked-out installer. Separately review the bootstrap itself. The default follows main, which can change.

Configure the server#

The installer asks for machine name, workspace root, project-scanning folder, optional API key and number of Claude accounts. It installs dependencies and creates the remote-harness-agent systemd service. Expose only the projects intended for sessions.

For multiple accounts, follow the installer's profile instructions and authenticate each profile. For one account, run claude and follow its login flow if needed. A login in one profile does not authorize all profiles.

Configuration stays in the agent's environment file on the server. The installer creates it owner-only. Review service account and file permissions before giving it sensitive projects; do not commit the environment file.

Verify the connection#

systemctl status remote-harness-agent
journalctl -u remote-harness-agent -n 80 --no-pager

Expect an active service and an online machine in the app. Start New chat, select a project, and ask it to list files or explain a README. Confirm that works before requesting edits or deployment. The hub can distribute MCP configuration; actual tools depend on connected integrations and credentials.

Permissions and approvals#

Review the session mode first. Start in planning/default mode rather than bypass. Read-only tools can be allowed automatically; writes and operational commands may need approval. Do not disable checks to cure connectivity or authentication errors.

The workspace setting and managed command policy help constrain normal sessions but do not provide OS isolation. Use a dedicated account, scoped provider credentials and separate environments. See Permissions and approvals.

Recovery#

Rerunning with HUB_URL and HUB_TOKEN updates those values on an existing installation and restarts the service. Check live sessions before restarting. Redact paths, credentials and project output from logs before sharing.

Stop or remove the agent#

sudo systemctl disable --now remote-harness-agent

Revoking hub access and stopping the OS service are separate steps. Keep needed project/session files before removing the checkout or configuration. For self-hosted hubs, use the repository's setup instructions; this guide covers connecting an agent.

Related: Machines, MCP, Troubleshooting.