---
title: Connect a VM
group: Use Escanor
order: 5
summary: Install the outbound agent on a Linux server you own, configure its workspace, and recover a disconnected machine.
updated: 2026-10-06
---
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](/docs/computers-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.

```sh
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](https://github.com/yashmishra2006/remote-harness-for-vms). Download and review it before running:

```sh
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:

```sh
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

```sh
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](/docs/permissions-approvals).

## Recovery

| Symptom | Check | Recovery |
|---|---|---|
| Service fails immediately | Logs, Node version, executable paths | Fix the reported prerequisite or dependency; rerun the installer if needed. |
| Active service, offline machine | Hub URL/token, DNS/TLS, outbound connectivity | Compare with the current app command; fix credentials rather than opening inbound ports. |
| Online machine, failed chat | Claude profile and directory | Authenticate that profile; verify directory access. |
| Operation denied | Approval and policy | Review the action and approve only the intended scope. |
| Exposed token | Hub credential controls | Rotate the token and update all affected agents. |

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

```sh
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](/docs/machines), [MCP](/docs/mcp), [Troubleshooting](/docs/troubleshooting).