Hub Dispatch

Hub Dispatch lets the agent send a task to a remote muxd node and collect the result, without leaving your local session. It is useful when a task needs to run on a specific machine — for example, running a Linux-only test suite from a Mac, or triggering a deployment from a node that has the right credentials.

Prerequisites

Both the local node and the remote node must be registered with the same hub. See the hub documentation for setup instructions.

Tools

hub_discovery

Lists all nodes currently connected to the hub, along with their reported capabilities:

hub_discovery

Example output:

Nodes connected to hub:
  linux-ci    linux/amd64   tools: bash, file_read, file_write, git
  mac-build   darwin/arm64  tools: bash, file_read, file_write, xcode
  staging     linux/amd64   tools: bash, file_read, docker, kubectl

Use this before dispatching to confirm the right node is available and has the tools you need.

hub_dispatch

Sends a prompt to a specific node and returns the output when the remote session completes:

hub_dispatch node=linux-ci prompt="Run the full test suite and report any failures"

muxd resolves the node, creates a new session on it, submits the prompt, and streams the output back to your local session. The remote agent runs with the full tool set available on that node.

How It Works

1. The local agent calls hub_dispatch with a node name and a prompt.
2. The hub routes the request to the named node.
3. The remote node creates a new session and starts the agent loop with the given prompt.
4. Output is streamed back through the hub and printed in the local TUI as it arrives.
5. When the remote session ends, the final result is returned as the tool result.

The remote session is independent — it has its own working directory, tool set, and context. It does not share memory or state with the local session beyond what is included in the dispatch prompt.

Use Cases

Constraints