SiteRPC

CLI-first SiteRPC runtime for exposing Playwright-controlled pages as callable tools.

Install

Install the full runtime on the worker machine:

npm install siterpc

Install the lightweight remote client on machines that only call an existing worker:

npm install siterpc-client

Quick Start

Create a generic starter project:

npx siterpc init my-site
cd my-site

Download the example project from a GitHub repository:

npx siterpc example your-org/site-rpc

Copy that repository's templates/example/ into a local directory:

npx siterpc example your-org/site-rpc ./my-example

Help

siterpc --help
siterpc help call
siterpc help example

Config Discovery

Local runtime commands automatically look for a config file from the current directory upward in this order:

1. siterpc.config.ts
2. siterpc.config.mjs
3. siterpc.config.js

You can still override discovery explicitly:

siterpc call --config ./siterpc.config.ts --tool app_search --input '{"keyword":"hello"}'

--remote ws://... always bypasses local discovery.

Runtime Commands

Call a tool with local config discovery:

siterpc call --tool app_someTool --input '{"key":"value"}'

Inspect worker state:

siterpc status

Close one site page:

siterpc close-page --accountId default --siteName app

Stop the local worker:

siterpc stop

Run a foreground worker explicitly:

siterpc worker --config ./siterpc.config.ts --listen-host 127.0.0.1 --listen-port 42100

Call a remote worker:

siterpc call --remote ws://127.0.0.1:42100 --tool app_someTool --input '{"key":"value"}'

Use the lightweight client when the caller does not need local browser control:

siterpc-client call --remote ws://127.0.0.1:42100 --tool app_someTool --input '{"key":"value"}'
siterpc-client status --remote ws://127.0.0.1:42100

Config Shape

import { defineConfig } from "siterpc";
import appSite from "./sites/app.js";

export default defineConfig({
  browser: {
    channel: "chrome",
    headless: false,
    defaultTimeout: 30_000,
    args: ["--disable-blink-features=AutomationControlled"]
  },
  resources: {
    root: "./resources"
  },
  accounts: [
    {
      id: "default",
      userDataDir: "./.siterpc-browser-data/default",
      sites: ["app"]
    }
  ],
  sites: [appSite]
});

Declarative Sites

import { defineSite } from "siterpc";

export default defineSite({
  name: "app",
  displayName: "App Site",
  globalIntercepts: [],
  pages: {
    main: {
      url: "https://example.com/",
      intercepts: []
    }
  },
  tools: []
});

For a complete real-world reference, use siterpc example <owner/repo>.