parchi-relay

# Parchi Relay (How To Use It) This skill documents how to run the Parchi relay daemon, connect the browser extension as an agent, and use the CLI to drive browser automation. ## What You Get - A local relay daemon (`/v1/rpc` + `/v1/extension`) that brokers calls. - A browser extension agent that connects to the daemon over WebSocket and executes browser tools. - A CLI (`parchi-relay` / `npm run relay`) that can: - list agents - pick the default agent - list tools / call tools - run an agent task and wait for completion ## Quickstart (Local) 1. Build everything: ```bash npm install npm run build ``` 2. Start the relay daemon (terminal A): ```bash npm run relay:daemon -- --token=<YOUR_TOKEN> --host=127.0.0.1 --port=17373 ``` 3. Load the extension (Chrome): - Open `chrome://extensions` - Enable Developer mode - Load unpacked: `dist/` - Open the extension sidepanel - Settings -> Relay: - Enable: `On` - URL: `http://127.0.0.1:17373` - Token: `<YOUR_TOKEN>` - Click `Apply` 4. Confirm the agent is connected (terminal B): ```bash npm run relay -- agents --token=<YOUR_TOKEN> ``` ## CLI Usage (Real Commands) The CLI talks to the daemon over HTTP JSON-RPC. Set env vars (recommended): ```bash export PARCHI_RELAY_TOKEN="<YOUR_TOKEN>" export PARCHI_RELAY_HOST="127.0.0.1" export PARCHI_RELAY_PORT="17373" ``` List agents: ```bash npm run relay -- agents ``` Doctor (sanity-check daemon, auth, agent connection, tool forwarding): ```bash npm run relay -- doctor ``` Get/set default agent: ```bash npm run relay -- default-agent get npm run relay -- default-agent set agent-123 ``` List tools (on default agent or a specific agent): ```bash npm run relay -- tools npm run relay -- tools --agentId=agent-123 ``` Call a tool: ```bash npm run relay -- tool getTabs --args='{}' npm run relay -- tool getContent --args='{\"mode\":\"text\"}' ``` Run a full agent task and wait for completion: ```bash npm run relay -- run "On the active tab, extract the main headline." --tabs=active --timeoutMs=600000 ``` ## RPC Surface (What The Relay Exposes) Relay daemon (`POST /v1/rpc`, `Authorization: Bearer <token>`): - `relay.ping` - `agents.list` - `agents.default.get` - `agents.default.set` `{ agentId }` - `tools.list` `{ agentId? }` - `tool.call` `{ tool, args, agentId? }` - `agent.run` `{ prompt, selectedTabIds?, agentId? }` - `run.wait` `{ runId, timeoutMs? }` - `run.events` `{ runId }` Extension agent (WebSocket `/v1/extension?token=...`): - Sends: `agent.hello` (registers the agent) - Receives: JSON-RPC requests (forwarded by daemon) - Sends: JSON-RPC responses - Can publish: `run.event` / `run.done` notifications (for streamed run telemetry) ## Troubleshooting - `agents` returns `[]`: - confirm daemon token matches extension token - confirm you loaded `dist/` (not `packages/extension/`) - in the extension, Settings -> Relay should show connected status (and any error message) - Tool calls fail due to policy: - check the extension Settings -> Tool Permissions and Allowed Domains ## Notes For Production Use - Keep the relay token private. Treat it like a local admin password. - Bind to `127.0.0.1` unless you explicitly intend to expose it. - If you expose it beyond localhost, add additional auth and transport security. ## Electron Agent Mode Parchi now supports a dedicated relay-native Electron agent: ```bash # Terminal A PARCHI_RELAY_TOKEN=<TOKEN> npm run relay:daemon # Terminal B PARCHI_RELAY_TOKEN=<TOKEN> npm run electron:agent ``` Managed helper (recommended): ```bash npm run electron:secure -- start npm run electron:secure -- status npm run electron:secure -- stop ``` Then select the Electron agent with: ```bash npm run relay -- agents npm run relay -- default-agent set <electron-agent-id> ``` Useful methods: - `tool.call` with `electron.launch` - `tool.call` with `electron.connect` - `tool.call` with `electron.snapshot`, `electron.click`, `electron.type`, `electron.press`