feat: remote spawn — dispatch agents to named brokers across machines

[prefrontalsys]

Problem

Agent Relay's distributed messaging works beautifully across machines — multiple brokers sharing a workspace key can exchange messages, DMs, and channel posts in real-time. But spawning is local-only. Every agent-relay spawn and agent.add MCP call creates a process on the machine running the broker that receives the command.

This means there's no way to say "spawn a Claude agent on my VPS broker from my laptop" without SSH-ing into the VPS and running the command there.

Use Case

I run Agent Relay on 3 machines over a Tailscale mesh (Mac, Oracle VPS, Ubuntu mini-PC), all sharing one workspace key. I want to:

1. Close my Mac laptop and hand off a running task to the VPS
2. From any machine's CLI/MCP/dashboard, spawn an agent on a specific remote broker
3. Use the dashboard's "Spawn Agent" button to target a remote broker, not just the local one

Today this requires SSH. The workspace messaging plumbing is already cross-machine — spawning is the missing piece.

Proposed API

# CLI: target a named remote broker
agent-relay spawn coder claude "Implement the plan" --broker vps-broker

# MCP: agent.add with broker target
agent.add(name: "coder", cli: "claude", task: "...", broker: "vps-broker")

# Dashboard: broker selector dropdown in spawn dialog

How It Could Work

The plumbing already exists:

• Brokers have identities in the workspace
• The workspace messaging layer is real-time and cross-machine
• AgentSpawnRequested is already a WebSocket event type

A remote spawn could be a workspace message from the requesting broker to the target broker: "spawn this agent with these parameters." The target broker processes it like a local spawn. The requesting broker gets a confirmation event back.

Security Consideration

Remote spawn = remote code execution. This should be opt-in per broker (e.g. --accept-remote-spawn flag or a config allowlist of trusted broker identities). Default: reject remote spawn requests.

Environment

• Agent Relay v6.0.0
• 3 machines on Tailscale mesh, shared workspace key
• All brokers can message each other; spawning is the only local-only operation

[willwashburn]

Love it. Solid use case.

The cross-broker plumbing is mostly there, but three things block remote targeting today:

1. Brokers don't announce an identity to Relaycast — they connect with a workspace key but don't say "I'm
   the VPS one," so there's no address to target.
2. SpawnAgentRequest has no target / broker field.
3. The wire schemas are strict, so we can't smuggle a target field through unrecognized — it'd be
   stripped before brokers see it.

Today, agent.spawn_requested is broadcast to every broker in the workspace and the first one to dedup
the event wins. First-come and non-deterministic by design.

We'd basically need to add more to the wire schema so we can tag hostname/broker-name or something.

Plan

Updates to https://github.com/AgentWorkforce/relaycast for hostname/name/targeting/envelope data — broker
identity announced on connect, optional target_broker on SpawnAgentRequest and
agent.spawn_requested, and a broker.list API so the CLI/MCP/dashboard can enumerate targets.

Then on the broker side: add deterministic routing when a target broker is named — falling back to
today's first-come dedup when it isn't. CLI gets --broker <name>, MCP agent.add gets a broker
field, dashboard gets a selector in the spawn dialog.

On unicast vs. broadcast: leaning broadcast-with-skip. Every broker keeping a consistent view of "a spawn
happened on vps" is useful for dashboards and agent listings, and it keeps routing on relaycast simple.
We can revisit if spawn payloads ever need to be confidential between brokers — not a concern today.

Security: opt-in per broker via --accept-remote-spawn (default off), exactly as you proposed. Brokers
that haven't opted in get rejected upstream with a clear error rather than silently ignoring the request.
A trusted-peer allowlist is a reasonable v2 once basic targeting is in.

Sequencing

Has to land in this order: (1) relaycast service + shared types, (2) agent-relay broker CLI/MCP, (3)
dashboard. All schema changes are additive, so old brokers and clients keep working until they upgrade.

@prefrontalsys Happy to take a PR if you're interested or I can start work on it in the next few weeks.

[willwashburn]

@prefrontalsys separately, would love to know more about your setup if you're willing to show me. email us at hi @ agentrelay.com would love to chat

[prefrontalsys]

FYI — while setting up for this on Mac + Oracle VPS today, I hit a v6.0.2 issue that breaks the precondition this feature request is built on: shared RELAY_API_KEY across machines causes the broker to exit at the WebSocket subscription step with "Unable to connect", even though HTTP registration succeeds and the cloud lists both agents under the same workspace.

Filed the full reproduction at #797. Once that's resolved, this remote-spawn work would build on a working messaging fabric.