Remote host support — spawn and connect to a broker on any machine

[khaliqgant]

Overview

Allow users to register any remote machine (cloud VM, beefy workstation, CI box) as a host in Pear, then run project workspaces and agents on that machine as if they were local. Terminal, file editor, and agent graph all behave the same regardless of where the broker is running.

Prerequisite: #125 — the broker binary must support joining an existing relay workspace by key before remote brokers can participate in a project's shared workspace.

---

Background

Today Pear supports two broker modes:

• Local: spawned on the user's machine via AgentRelayClient.spawn() (broker.ts:1307-1323)
• Cloud (Daytona): provisioned on demand via the Agent Relay Cloud API (cloud-agent.ts:1067-1080)

There is no way to register an arbitrary machine the user already controls. The broker binary (crates/broker/ in the relay repo) can already run anywhere — the gap is entirely in Pear's registration, connection, and UI layers. The connection primitive itself is proven: attachCloudSandbox() (broker.ts:1467) already connects to a remote broker by execUrl + apiKey, and the cloud path uses this in production every day.

---

What Needs to Be Built

1. Hosts store

Persist registered remote machines in the project store alongside the existing relay workspace record.

type RemoteHost = {
  id: string
  name: string          // user-facing label, e.g. "Mac Pro", "AWS dev box"
  url: string           // broker HTTP endpoint
  apiKey: string        // broker auth token
  createdAt: number
}

Add to store.ts: getHosts(), addHost(), removeHost().

2. Generalized attachRemoteHost() in broker.ts

Extract from attachCloudSandbox() and remove Daytona-specific concerns:

• Remove the 60-second lease renewal timer (not needed for persistent machines)
• Remove sandboxId / Daytona fields
• Add workspaceKey passthrough (from Cloud agents land in a separate relay workspace from local agents — can't communicate #125) so the remote broker joins the project's existing workspace
• Keep the same AgentRelayClient connection and session keying pattern

attachCloudSandbox() can then become a thin wrapper around attachRemoteHost() that adds the lease renewal on top.

3. IPC handlers

• broker.registerHost(url, apiKey, name) → validates connectivity, persists, returns RemoteHost
• broker.listHosts() → all registered hosts
• broker.removeHost(id)
• broker.start(projectId, { hostId? }) — optional hostId routes to a registered remote host instead of spawning locally

4. Project association

When starting a project, let the user choose which host to run it on. Default is still local spawn. The chosen host is stored per-project (add hostId?: string to the Project type in store.ts).

5. UI

• Hosts settings page — list registered hosts with name, URL, last-seen status, remove button
• Add host dialog — paste URL + API key, Pear validates connectivity before saving
• Host picker in project setup — dropdown to select local or a registered remote host when opening a project

6. Installation story on the remote machine

The user needs a way to start the broker on a remote machine. Options:

• CLI: agent-relay start --daemon (similar to superset start --daemon) — exposes the broker and prints the URL + API key to paste into Pear
• Docker: single docker run agentworkforce/relay command

The broker binary already exists in crates/broker/ in the relay repo. The work here is packaging it as an easily installable standalone CLI/image and documenting the setup flow.

---

What This Unlocks

• Run agents on a more powerful machine without leaving Pear on your laptop
• Share a single beefy host across multiple projects
• Run agents on a cloud VM for long-running tasks without keeping your laptop awake
• Foundation for the multi-user workspace feature (Remote host support — spawn and connect to a broker on any machine #126) — multiple Pear instances can connect to the same remote host's broker

---

Files Involved

File	Change
src/main/store.ts	Add RemoteHost type, getHosts, addHost, removeHost
src/main/broker.ts	Add attachRemoteHost(), update attachCloudSandbox() to wrap it, add hostId routing in start()
src/main/schemas.ts	Add RemoteHost Zod schema
src/shared/types/ipc.ts	Add broker.registerHost, broker.listHosts, broker.removeHost IPC calls
src/renderer/src/components/settings/	Hosts settings page + add host dialog
src/renderer/src/stores/project-store.ts	Add hostId to project type
relay repo	Standalone CLI packaging for the broker binary

---

Estimated Effort

~1 week (Pear side), plus relay CLI packaging work.