@myprojectmachine/pm-bridge

Bridge: connects an OpenClaw mesh to a Project Machine relay so that questions asked in a PM canvas reach a live OC session and that session's reply streams back to the user.

The bridge runs on each OC host (e.g. your Mac mini, a home server, a VPS) and is paired with one AgentConnection in Project Machine via a capability token.

Install

The recommended path is install — one command that saves the config AND sets up a process supervisor so the bridge starts at login and restarts on crash (launchd on macOS, systemd --user on Linux):

npx --yes @myprojectmachine/pm-bridge install <token> \
  --relay wss://myprojectmachine.com/relay \
  --agent main \
  --session-key agent:main:project-machine-canvas \
  --host my-mac-mini

Logs land in ~/.mpm-bridge/bridge.log (macOS) or journalctl --user -u pm-bridge (Linux). On Linux, to keep the bridge running when you're not logged in: sudo loginctl enable-linger $USER (once). Remove the supervisor with pm-bridge uninstall.

To run in the foreground instead (first-time smoke test, debugging):

npx --yes @myprojectmachine/pm-bridge connect <token> \
  --relay wss://myprojectmachine.com/relay --agent main

First run

In Project Machine, click Connect on an agent, copy the bridge command shown, and run it on the machine that hosts your OpenClaw mesh. The agent's badge in PM flips to Live once the bridge authenticates.

connect stays in the foreground, prints a small event log, and reconnects automatically if the socket drops. Ctrl-C to stop.

The token, relay URL, and agent id are saved to ~/.mpm-bridge/config.json (mode 0600). Subsequent foreground runs:

npx --yes @myprojectmachine/pm-bridge resume

install with no token argument reuses the saved config — so connect once, then npx --yes @myprojectmachine/pm-bridge install upgrades a foreground setup to a supervised one.

How it works

1. Bridge dials the PM relay over WSS, sends a hello frame with the capability token.
2. The relay validates the token and registers the socket with its in-process dispatcher.
3. When the canvas asks a question, PM sends an ask frame on the socket.
4. The bridge shells out to openclaw agent --agent <id> --message "…" --json in a child process.
5. When the agent returns, the bridge sends a done frame with the reply text and a provenance string (<agent> · <host> · <duration>).

Failure modes map cleanly to the frame protocol:

• decline — runner timed out or was aborted.
• error — the agent crashed, JSON couldn't be parsed, or anything else.

create-agent — agent-creates-agent

pm-bridge create-agent lets any OC agent (or human at a shell) mint a new Project Machine Prompt Agent from a plain-text description. It chains PM's two-step flow: POST /api/workbench/prompt-agents/draft (LLM drafts name + system prompt + tagline) → POST /api/workbench/agents (persists in the token's tenant).

It authenticates with a PM agent token (pmat_…, scope agents:write) — not the bridge capability token. Provide it via --token-file <path> (JSON {"token":"pmat_…"}) or the PM_AGENT_TOKEN env var.

# Preview only — prints {draft} JSON, persists nothing:
pm-bridge create-agent "Healthcare insurance expert focused on Medicare \
  Advantage plan comparisons" --token-file ~/.pm/token.json --draft-only

# Draft + persist; prints {agent} JSON on stdout:
pm-bridge create-agent "…" --token-file ~/.pm/token.json --model claude-opus-4-7

• --model sets the created agent's modelName (default claude-sonnet-4-6); PM validates it server-side, so the bridge never needs a release when PM's model list changes.
• --base-url overrides the PM API base. Without it, the base is derived from the saved bridge config's relayUrl (wss://host/relay → https://host), falling back to https://myprojectmachine.com.
• Status lines go to stderr; stdout is JSON-only so calling agents can parse the result directly.

Configuration

The state file at ~/.mpm-bridge/config.json holds:

| Field | Required | Notes | |--------------|----------|--------------------------------------------------------| | relayUrl | yes | WSS endpoint of the PM relay. | | token | yes | Capability token (shown once in PM). | | agentId | yes | OC agent to dispatch to. Defaults to main. | | sessionKey | no | Explicit OC session key for routing. | | host | no | Display label used in provenance strings. |

Security

• The raw token only lives in this file on disk and in transit over the WSS handshake. The PM relay never stores the raw token — only its sha-256 hash.
• Token revocation is initiated from PM (Connect modal → Disconnect). The relay rejects revoked tokens with WS close code 4001 and the bridge does not reconnect on 4001.
• Tokens expire 90 days after mint. Manual rotation only for v1.

Naming note

Prior to v0.2.0 this package was published as @junoroe/project-machine-bridge with a mpm-bridge bin name. The public rename to @myprojectmachine/pm-bridge

• pm-bridge bin is a breaking change for anyone who scripted around the old identifiers. The on-disk config path (~/.mpm-bridge/config.json) is unchanged to keep existing installs running through the transition.

v0.3.0 adds install / uninstall (supervisor setup) — additive, no breaking changes.

License

MIT.