@remcp/remcp 0.1.4 → 0.2.4

package/README.md

@@ -1,92 +1,71 @@
-<p align="center">
-  <img src="./assets/remcp-logo.png" width="168" alt="ReMCP logo">
-</p>
+# Device client
 
-<h1 align="center">ReMCP</h1>
-
-<p align="center"><strong>Your computer. Your tools. One secure MCP connection.</strong></p>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/@remcp/remcp"><img alt="npm" src="https://img.shields.io/npm/v/%40remcp%2Fremcp?style=flat-square&label=npm"></a>
-  <a href="https://www.npmjs.com/package/@remcp/remcp"><img alt="downloads" src="https://img.shields.io/npm/dm/%40remcp%2Fremcp?style=flat-square&label=downloads"></a>
-  <img alt="Node.js" src="https://img.shields.io/node/v/%40remcp%2Fremcp?style=flat-square&label=node">
-  <a href="./LICENSE"><img alt="license" src="https://img.shields.io/npm/l/%40remcp%2Fremcp?style=flat-square"></a>
-  <a href="https://github.com/antonbaider/remcp/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/antonbaider/remcp?style=flat-square"></a>
-</p>
-
-<p align="center">
-  <a href="https://remcp.delio24.com">Website</a> ·
-  <a href="https://remcp.delio24.com/docs">Docs</a> ·
-  <a href="https://remcp.delio24.com/security">Security</a> ·
-  <a href="https://remcp.delio24.com/support">Support</a>
-</p>
-
-ReMCP is the lightweight device client that connects a computer you own or administer to your ReMCP workspace. The agent makes an outbound connection only; you do not need to expose an inbound port on the machine.
-
-## Install
-
-**Requires Node.js 22.5 or newer.**
+`@remcp/remcp` is the ReMCP device client. It pairs a computer with ReMCP, installs the first-party
+local runtime, and runs the outbound-only agent that serves your MCP client's tool calls.
 
 ```bash
 npm install --global @remcp/remcp@latest
+remcp --version
+remcp status
 ```
 
-Then open **[ReMCP → Connect a machine](https://remcp.delio24.com/app/connect)** and generate a one-time pairing command. Run that exact command on the computer you want to connect.
-
-> Pairing codes are generated in the authenticated workspace, expire automatically, and are single-use. Do not invent or reuse a code from documentation.
+Pairing commands are generated in the workspace at <https://remcp.delio24.com/app/connect>. The
+generated command runs `remcp connect --server … --code … --install`, which stores a per-device
+credential under `~/.config/remcp/`, installs the runtime from npm, and registers a user service
+(systemd on Linux, LaunchAgent on macOS, Scheduled Task on Windows).
 
 ## Commands
 
-| Command | Purpose |
-| --- | --- |
-| `remcp start` | Start the device agent in the foreground |
-| `remcp status` | Show pairing and service health |
-| `remcp doctor` | Run the same connectivity diagnostics in JSON form |
-| `remcp install` | Install the persistent Linux user service |
-| `remcp update` | Update ReMCP and the compatible local runtime |
-| `remcp uninstall` | Stop and remove the user service |
-| `remcp uninstall --purge` | Remove the service and global packages |
-| `remcp --version` | Print the installed client version |
+```text
+remcp start                  Run the device agent in the foreground
+remcp status                 Show version, pairing, runtime, telemetry and server health as JSON
+remcp doctor                 Alias for status
+remcp update                 Update the client and runtime, then restart the user service
+remcp install                Install or repair the user service
+remcp uninstall              Remove the user service
+remcp uninstall --purge      Remove the service and the global packages
+remcp telemetry [status|on|off]
+remcp --version
+```
 
-## How pairing works
+`remcp status` reports the runtime the device would install, whether the agent service is running,
+and the current usage-metrics state, so a support request can be answered with one paste.
 
-1. Sign in to your ReMCP workspace.
-2. Generate a one-time pairing command.
-3. Run the command on your machine.
-4. ReMCP stores the device credential locally with restrictive permissions.
-5. The agent establishes an outbound WebSocket connection to the configured ReMCP service.
+## What runs on your computer
 
-For the official service, compatible runtime metadata is delivered as part of the pairing response. A custom ReMCP server must be explicitly trusted with `--trust-runtime` before the client accepts runtime metadata from it.
+- the agent (`remcp start`), which holds the device credential and dials
+  `wss://remcp.delio24.com/agent`;
+- [`@remcp/runtime`](https://www.npmjs.com/package/@remcp/runtime), spawned by the agent as an MCP
+  stdio server. The runtime executes the tools, opens no network connection, and is supervised: if it
+  exits, the agent restarts it with backoff and reports the restart instead of failing silently.
 
-## Security model
+Configuration lives in `~/.config/remcp/config.json` (client) and `~/.config/remcp/runtime.json`
+(runtime: allowed roots, blocked commands, output and write limits, and the usage-metrics switch).
+Run `npx @remcp/runtime --describe` to print the runtime's effective configuration.
 
-- Outbound-only device connection.
-- Per-device revocable credential.
-- Local client configuration stored with restrictive permissions.
-- Runtime metadata validated before installation.
-- Custom servers require an explicit runtime trust decision.
-- No pairing secrets belong in issues, screenshots, logs, or documentation.
+## Usage metrics
 
-If a machine should no longer be connected, revoke it from the workspace and remove the local service.
+Opt-out, self-hosted, and limited to tool names, timings, outcomes, error classes, and device health
+samples. No paths, no commands, no arguments, no output, no third-party endpoint, no install ping.
+Disable with `remcp telemetry off` or `REMCP_RUNTIME_DISABLE_TELEMETRY=1`; the switch applies to both
+the client and the runtime, and restarts the service so it takes effect immediately.
 
-## Update
+## Security
 
-```bash
-remcp update
-remcp --version
-remcp status
-```
+- Outbound-only connection; the machine never listens.
+- One revocable credential per paired device, stored with restrictive permissions.
+- Runtime metadata from a custom server is only accepted with an explicit `--trust-runtime`.
+- Revoking a device in the workspace closes the connection; the agent then stops retrying and says so
+  instead of reconnecting forever.
 
 ## Development
 
 ```bash
-npm ci
+npm install
 npm run check
 npm test
-npm audit --omit=dev
-npm pack --dry-run
 ```
 
 ## License
 
-MIT © ReMCP contributors. See [LICENSE](LICENSE).
+MIT.

package/package.json

@@ -1,13 +1,22 @@
 {
   "name": "@remcp/remcp",
-  "version": "0.1.4",
-  "description": "Secure ReMCP device client for connecting your computer to MCP over an outbound-only agent.",
+  "version": "0.2.4",
+  "description": "ReMCP device client: pair a computer with ReMCP and run the outbound-only agent that hosts the local MCP runtime.",
   "type": "module",
   "license": "MIT",
   "homepage": "https://remcp.delio24.com",
-  "bin": { "remcp": "bin/remcp.mjs" },
-  "engines": { "node": ">=22.5.0" },
-  "files": ["bin", "src", "LICENSE", "README.md"],
+  "bin": {
+    "remcp": "bin/remcp.mjs"
+  },
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "files": [
+    "bin",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
   "scripts": {
     "check": "node --check bin/remcp.mjs && node --check src/cli.mjs && node --check src/agent.mjs && node --check src/runtime.mjs && node --check src/version.mjs",
     "test": "node --test test/*.test.mjs"
@@ -16,9 +25,26 @@
     "@modelcontextprotocol/sdk": "^1.30.0",
     "ws": "^8.21.3"
   },
-  "overrides": { "sharp": "0.35.4", "uuid": "11.1.1" },
-  "repository": { "type": "git", "url": "git+https://github.com/antonbaider/remcp.git" },
-  "bugs": { "url": "https://github.com/antonbaider/remcp/issues" },
-  "publishConfig": { "access": "public" },
-  "keywords": ["mcp", "model-context-protocol", "remote", "computer", "cli", "agent", "chatgpt", "codex"]
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/antonbaider/remcp.git",
+    "directory": "packages/client"
+  },
+  "bugs": {
+    "url": "https://github.com/antonbaider/remcp/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "remote",
+    "computer",
+    "cli",
+    "agent",
+    "chatgpt",
+    "codex",
+    "self-hosted"
+  ]
 }

package/src/agent.mjs

@@ -10,6 +10,17 @@ import { normalizeRuntime } from './runtime.mjs';
 import { VERSION } from './version.mjs';
 
 const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+const METRICS_INTERVAL_MS = 60_000;
+const TELEMETRY_QUEUE_LIMIT = 500;
+const TELEMETRY_BATCH_LIMIT = 100;
+const TELEMETRY_SEND_INTERVAL_MS = 5_000;
+const RECONNECT_BASE_MS = 2_000;
+const RECONNECT_MAX_MS = 60_000;
+const RUNTIME_RESTART_BASE_MS = 1_000;
+const RUNTIME_RESTART_MAX_MS = 30_000;
+// Below the relay's RPC timeout so the model gets a real error instead of a client-side
+// timeout while the device keeps working invisibly.
+const CALL_TIMEOUT_MARGIN_MS = 10_000;
 
 function globalNodeModules() {
   const result = spawnSync(npmCommand, ['root', '--global'], { encoding: 'utf8' });
@@ -24,6 +35,28 @@ function localRuntimeEntry(runtimeValue) {
   return candidate;
 }
 
+function jitter(ms) {
+  return Math.round(ms * (0.75 + Math.random() * 0.5));
+}
+
+// Device health is sampled locally and is the only thing ReMCP stores about the machine
+// beyond its name, platform and last-seen time. No process list, no file names.
+function deviceMetrics(extra = {}) {
+  const load = os.loadavg?.()[0] ?? 0;
+  const totalMem = os.totalmem();
+  const freeMem = os.freemem();
+  return {
+    uptimeSeconds: Math.round(os.uptime()),
+    agentUptimeSeconds: Math.round(process.uptime()),
+    rssBytes: process.memoryUsage().rss,
+    load1: Number.isFinite(load) ? Number(load.toFixed(2)) : 0,
+    cpuCount: os.cpus?.().length ?? 0,
+    freeMemoryRatio: totalMem > 0 ? Number((freeMem / totalMem).toFixed(3)) : 0,
+    agentVersion: VERSION,
+    ...extra,
+  };
+}
+
 export async function runAgent(options) {
   const serverUrl = String(options.serverUrl || '').replace(/\/$/, '');
   const deviceToken = String(options.deviceToken || '');
@@ -31,25 +64,137 @@ export async function runAgent(options) {
   const deviceName = String(options.deviceName || os.hostname());
   if (!serverUrl || !deviceToken || !deviceId) throw new Error('serverUrl, deviceToken and deviceId are required');
   const agentUrl = serverUrl.replace(/^http/, 'ws') + '/agent';
-  const reconnectMs = Number(options.reconnectMs || 3000);
+  const callTimeoutMs = Math.max(5_000, Number(options.rpcTimeoutMs || 120000) - CALL_TIMEOUT_MARGIN_MS);
+  const telemetryEnabled = options.telemetryEnabled !== false;
+  const persistState = typeof options.persistState === 'function' ? options.persistState : () => {};
   let stopping = false;
   let activeSocket;
+  let reconnects = 0;
+  let pendingRequests = 0;
+  let runtimeVersion = 'unknown';
+  let runtimeRestarts = 0;
+  let runtimeDown = false;
+  const telemetryQueue = [];
+  let telemetryTimer = null;
+  const runtimeEntry = localRuntimeEntry(options.runtime);
+
+  // --- local runtime supervision ------------------------------------------------------
+  // If the runtime dies (a bad shell, a broken pipe, an OOM) the agent used to stay
+  // "online" forever and every later call failed with an opaque "Not connected". Now the
+  // transport is watched and the runtime is restarted with backoff.
+  let mcp = null;
+  let transport = null;
+  let runtimeRestartDelay = RUNTIME_RESTART_BASE_MS;
+
+  function runtimeEnv() {
+    // The SDK's stdio transport does not inherit the environment by default; spreading
+    // process.env here is what gives the runtime its REMCP_RUNTIME_* configuration, PATH,
+    // HOME and the telemetry opt-out.
+    const env = { ...process.env };
+    if (!telemetryEnabled) env.REMCP_RUNTIME_DISABLE_TELEMETRY = '1';
+    return env;
+  }
 
-  const mcp = new Client({ name: 'remcp-agent', version: VERSION });
-  const transport = new StdioClientTransport({ command: process.execPath, args: [localRuntimeEntry(options.runtime)] });
-  await mcp.connect(transport);
-  console.log('ReMCP local runtime ready');
+  async function startRuntime() {
+    if (stopping) return;
+    runtimeDown = false;
+    const client = new Client({ name: 'remcp-agent', version: VERSION });
+    const stdio = new StdioClientTransport({ command: process.execPath, args: [runtimeEntry], env: runtimeEnv() });
+    mcp = client;
+    transport = stdio;
+    client.fallbackNotificationHandler = async notification => {
+      if (!telemetryEnabled) return;
+      if (notification?.method !== 'notifications/remcp/telemetry') return;
+      const events = Array.isArray(notification.params?.events) ? notification.params.events : [];
+      if (!events.length) return;
+      if (notification.params?.runtimeVersion) runtimeVersion = String(notification.params.runtimeVersion);
+      for (const event of events) {
+        if (telemetryQueue.length >= TELEMETRY_QUEUE_LIMIT) telemetryQueue.shift();
+        telemetryQueue.push(event);
+      }
+    };
+    stdio.onclose = () => handleRuntimeExit('closed');
+    stdio.onerror = error => console.error(`ReMCP local runtime error: ${error instanceof Error ? error.message : String(error)}`);
+    try {
+      await client.connect(stdio);
+      runtimeVersion = client.getServerVersion()?.version || runtimeVersion;
+      runtimeRestarts += 1;
+      runtimeRestartDelay = RUNTIME_RESTART_BASE_MS;
+      console.log(`ReMCP local runtime ready (${runtimeVersion})`);
+      send({ type: 'metrics', metrics: deviceMetrics({ reconnects, pendingRequests, runtimeVersion, runtimeRestarts, runtimeDown: false }) });
+      if (runtimeRestarts > 1) queueEvent({ event: 'runtime_restart', at: Date.now(), count: runtimeRestarts, success: true });
+    } catch (error) {
+      console.error(`ReMCP local runtime failed to start: ${error instanceof Error ? error.message : String(error)}`);
+      handleRuntimeExit('failed');
+    }
+  }
+
+  function handleRuntimeExit(reason) {
+    if (stopping || runtimeDown) return;
+    runtimeDown = true;
+    const delay = jitter(runtimeRestartDelay);
+    runtimeRestartDelay = Math.min(RUNTIME_RESTART_MAX_MS, runtimeRestartDelay * 2);
+    console.error(`ReMCP local runtime ${reason}; restarting in ${delay}ms`);
+    queueEvent({ event: 'runtime_down', at: Date.now(), reason: reason.slice(0, 24) });
+    send({ type: 'metrics', metrics: deviceMetrics({ reconnects, pendingRequests, runtimeVersion, runtimeRestarts, runtimeDown: true }) });
+    setTimeout(() => { void startRuntime(); }, delay).unref?.();
+  }
+
+  // --- relay connection ---------------------------------------------------------------
+  function send(message) {
+    if (activeSocket?.readyState === 1) {
+      activeSocket.send(JSON.stringify(message));
+      return true;
+    }
+    return false;
+  }
+
+  function flushTelemetry() {
+    if (!telemetryEnabled || !telemetryQueue.length) return;
+    const batch = telemetryQueue.splice(0, TELEMETRY_BATCH_LIMIT);
+    if (!send({ type: 'telemetry', runtimeVersion, agentVersion: VERSION, events: batch })) telemetryQueue.unshift(...batch);
+  }
+
+  function queueEvent(event) {
+    if (!telemetryEnabled) return;
+    if (telemetryQueue.length >= TELEMETRY_QUEUE_LIMIT) telemetryQueue.shift();
+    telemetryQueue.push(event);
+  }
+
+  function reportInstallOnce() {
+    if (!telemetryEnabled || options.installReported === true) return;
+    if (send({
+      type: 'install',
+      agentVersion: VERSION,
+      runtimeVersion,
+      node: process.versions.node,
+      platform: process.platform,
+      arch: process.arch,
+      installSpec: String(options.installSpec || ''),
+    })) {
+      persistState({ installReported: true });
+      console.log('ReMCP reported this installation to your own workspace (disable with `remcp telemetry off`).');
+    }
+  }
 
   async function respond(ws, message) {
+    pendingRequests += 1;
     try {
       let result;
-      if (message.method === 'tools/list') result = await mcp.listTools();
-      else if (message.method === 'tools/call') result = await mcp.callTool(message.params);
-      else if (message.method === 'ping') result = { ok: true, hostname: os.hostname(), platform: process.platform, arch: process.arch, uptimeSeconds: Math.floor(os.uptime()) };
-      else throw new Error(`Unsupported relay method: ${message.method}`);
+      if (message.method === 'ping') {
+        result = { ok: true, hostname: os.hostname(), platform: process.platform, arch: process.arch, uptimeSeconds: Math.floor(os.uptime()), agentVersion: VERSION, runtimeVersion, runtimeRestarts };
+      } else if (!runtimeDown && mcp) {
+        if (message.method === 'tools/list') result = await mcp.listTools(undefined, { timeout: callTimeoutMs });
+        else if (message.method === 'tools/call') result = await mcp.callTool(message.params, undefined, { timeout: callTimeoutMs });
+        else throw new Error(`Unsupported relay method: ${message.method}`);
+      } else {
+        throw new Error('The ReMCP local runtime is restarting. Retry in a few seconds.');
+      }
       ws.send(JSON.stringify({ type: 'response', id: message.id, result }));
     } catch (error) {
       ws.send(JSON.stringify({ type: 'response', id: message.id, error: { message: error instanceof Error ? error.message : String(error) } }));
+    } finally {
+      pendingRequests = Math.max(0, pendingRequests - 1);
     }
   }
 
@@ -58,28 +203,67 @@ export async function runAgent(options) {
     const ws = new WebSocket(agentUrl, { headers: { Authorization: `Bearer ${deviceToken}` } });
     activeSocket = ws;
     ws.on('open', () => {
-      ws.send(JSON.stringify({ type: 'hello', deviceId, deviceName, hostname: os.hostname(), platform: process.platform, arch: process.arch, agentVersion: VERSION }));
+      reconnects = 0;
+      ws.send(JSON.stringify({
+        type: 'hello',
+        deviceId,
+        deviceName,
+        hostname: os.hostname(),
+        platform: process.platform,
+        arch: process.arch,
+        agentVersion: VERSION,
+        runtimeVersion,
+        telemetryEnabled,
+        reconnects,
+      }));
       console.log(`Connected to ${serverUrl} as ${deviceName}`);
+      send({ type: 'metrics', metrics: deviceMetrics({ reconnects, pendingRequests, runtimeVersion, runtimeRestarts, runtimeDown }) });
+      reportInstallOnce();
+      flushTelemetry();
     });
     ws.on('message', raw => {
       let message;
       try { message = JSON.parse(raw.toString()); } catch { return; }
       if (message?.type === 'request') void respond(ws, message);
     });
-    ws.on('close', () => { if (!stopping) setTimeout(connect, reconnectMs); });
+    ws.on('close', code => {
+      if (stopping) return;
+      if (code === 1008) {
+        // The relay closes with 1008 when the device was revoked. Retrying forever would
+        // hide that from the person at the computer.
+        console.error('ReMCP access for this device was revoked. Pair the machine again from the ReMCP workspace: remcp connect --server <url> --code <code> --install');
+        return;
+      }
+      reconnects += 1;
+      const delay = jitter(Math.min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * 2 ** Math.min(reconnects, 5)));
+      setTimeout(connect, delay);
+    });
     ws.on('error', error => console.error(`ReMCP relay: ${error.message}`));
   }
 
+  telemetryTimer = setInterval(() => {
+    if (activeSocket?.readyState === 1) {
+      send({ type: 'metrics', metrics: deviceMetrics({ reconnects, pendingRequests, runtimeVersion, runtimeRestarts, runtimeDown, queueDepth: telemetryQueue.length }) });
+      flushTelemetry();
+    }
+  }, METRICS_INTERVAL_MS);
+  telemetryTimer.unref?.();
+  const telemetryFlushTimer = setInterval(flushTelemetry, TELEMETRY_SEND_INTERVAL_MS);
+  telemetryFlushTimer.unref?.();
+
   async function stop() {
     if (stopping) return;
     stopping = true;
+    if (telemetryTimer) clearInterval(telemetryTimer);
+    clearInterval(telemetryFlushTimer);
     try { activeSocket?.close(); } catch {}
-    try { await mcp.close(); } catch {}
-    try { await transport.close(); } catch {}
+    try { await mcp?.close(); } catch {}
+    try { await transport?.close(); } catch {}
   }
 
   process.once('SIGINT', () => void stop().finally(() => process.exit(0)));
   process.once('SIGTERM', () => void stop().finally(() => process.exit(0)));
+  await startRuntime();
   connect();
-  return { stop };
+  return { stop, runtimeVersion: () => runtimeVersion, runtimeRestarts: () => runtimeRestarts, isRuntimeDown: () => runtimeDown };
 }

package/src/cli.mjs

@@ -3,6 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
 import { runAgent } from './agent.mjs';
 import { normalizeRuntime } from './runtime.mjs';
 import { PACKAGE_NAME, VERSION } from './version.mjs';
@@ -10,19 +11,26 @@ import { PACKAGE_NAME, VERSION } from './version.mjs';
 const home = os.homedir();
 const configDir = process.env.REMCP_CONFIG_DIR || path.join(home, '.config', 'remcp');
 const configFile = path.join(configDir, 'config.json');
-const serviceFile = path.join(home, '.config', 'systemd', 'user', 'remcp-agent.service');
+const runtimeConfigFile = path.join(configDir, 'runtime.json');
+const machineIdFile = path.join(configDir, 'machine-id');
+const linuxServiceFile = path.join(home, '.config', 'systemd', 'user', 'remcp-agent.service');
+const macServiceLabel = 'com.remcp.agent';
+const macServiceFile = path.join(home, 'Library', 'LaunchAgents', `${macServiceLabel}.plist`);
+const macLogFile = path.join(home, 'Library', 'Logs', 'remcp-agent.log');
+const windowsTaskName = 'ReMCP Agent';
 const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
 const officialOrigin = 'https://remcp.delio24.com';
 
 function parse(argv) {
   const [command = 'help', ...rest] = argv;
   const flags = {};
+  const positional = [];
   for (let i = 0; i < rest.length; i++) {
-    if (!rest[i].startsWith('--')) continue;
+    if (!rest[i].startsWith('--')) { positional.push(rest[i]); continue; }
     const key = rest[i].slice(2);
     flags[key] = rest[i + 1] && !rest[i + 1].startsWith('--') ? rest[++i] : true;
   }
-  return { command, flags };
+  return { command, flags, positional };
 }
 
 function run(command, args, options = {}) {
@@ -55,13 +63,77 @@ function saveConfig(value) {
   fs.chmodSync(configFile, 0o600);
 }
 
+function readJsonFile(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return {}; }
+}
+
+function writeJsonFile(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 });
+  fs.chmodSync(file, 0o600);
+}
+
+function flagEnabled(value) {
+  return value === undefined || value === null ? true : value !== false;
+}
+
+// One switch for the whole machine: the client and the runtime it spawns must agree,
+// otherwise the runtime would keep reporting after the user opted out.
+function telemetryState() {
+  const client = readJsonFile(configFile);
+  const runtime = readJsonFile(runtimeConfigFile);
+  const clientEnabled = flagEnabled(client.telemetryEnabled);
+  const runtimeEnabled = flagEnabled(runtime.telemetryEnabled);
+  return {
+    enabled: clientEnabled && runtimeEnabled,
+    clientEnabled,
+    runtimeEnabled,
+    installReported: client.installReported === true,
+    configFile,
+    runtimeConfigFile,
+    transport: 'paired-agent-only',
+    endpoint: null,
+    collects: 'tool names, durations, outcomes, error classes, and device health samples',
+    neverCollects: 'file paths, file contents, command strings, tool arguments, and tool output',
+    thirdParty: false,
+    installPing: false,
+    remoteFeatureFlags: false,
+  };
+}
+
+function setTelemetry(enabled) {
+  const client = readJsonFile(configFile);
+  client.telemetryEnabled = enabled;
+  writeJsonFile(configFile, client);
+  const runtime = readJsonFile(runtimeConfigFile);
+  runtime.telemetryEnabled = enabled;
+  writeJsonFile(runtimeConfigFile, runtime);
+  return telemetryState();
+}
+
+function ensureMachineId() {
+  fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
+  try {
+    const existing = fs.readFileSync(machineIdFile, 'utf8').trim();
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(existing)) return existing;
+  } catch {}
+  const value = randomUUID();
+  fs.writeFileSync(machineIdFile, value + '\n', { mode: 0o600 });
+  fs.chmodSync(machineIdFile, 0o600);
+  return value;
+}
+
+function servicePlatform() {
+  return process.env.NODE_ENV === 'test' && process.env.REMCP_TEST_PLATFORM ? process.env.REMCP_TEST_PLATFORM : process.platform;
+}
+
 function globalPrefix() {
   return output(npmCommand, ['prefix', '--global']);
 }
 
 function globalCliPath() {
   const prefix = globalPrefix();
-  return process.platform === 'win32' ? path.join(prefix, 'remcp.cmd') : path.join(prefix, 'bin', 'remcp');
+  return servicePlatform() === 'win32' ? path.join(prefix, 'remcp.cmd') : path.join(prefix, 'bin', 'remcp');
 }
 
 function npmGlobalInstall(...specs) {
@@ -72,33 +144,82 @@ function quoteSystemd(value) {
   return `"${String(value).replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
 }
 
+function xmlEscape(value) {
+  return String(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;');
+}
+
 function installLinuxService(cliPath = globalCliPath()) {
   const unit = `[Unit]\nDescription=ReMCP device agent\nAfter=network-online.target\nWants=network-online.target\n\n[Service]\nType=simple\nExecStart=${quoteSystemd(cliPath)} start\nRestart=always\nRestartSec=3\nNoNewPrivileges=true\n\n[Install]\nWantedBy=default.target\n`;
-  fs.mkdirSync(path.dirname(serviceFile), { recursive: true });
-  fs.writeFileSync(serviceFile, unit);
+  fs.mkdirSync(path.dirname(linuxServiceFile), { recursive: true });
+  fs.writeFileSync(linuxServiceFile, unit);
   run('systemctl', ['--user', 'daemon-reload']);
   run('systemctl', ['--user', 'enable', '--now', 'remcp-agent.service']);
 }
 
+function macLaunchDomain() {
+  if (typeof process.getuid !== 'function') throw new Error('Could not determine the current macOS user');
+  return `gui/${process.getuid()}`;
+}
+
+function installMacService(cliPath = globalCliPath()) {
+  const domain = macLaunchDomain();
+  const target = `${domain}/${macServiceLabel}`;
+  const cliScript = fs.realpathSync(cliPath);
+  fs.mkdirSync(path.dirname(macServiceFile), { recursive: true });
+  fs.mkdirSync(path.dirname(macLogFile), { recursive: true });
+  const plist = `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict>\n<key>Label</key><string>${macServiceLabel}</string>\n<key>ProgramArguments</key><array><string>${xmlEscape(process.execPath)}</string><string>${xmlEscape(cliScript)}</string><string>start</string></array>\n<key>RunAtLoad</key><true/><key>KeepAlive</key><true/>\n<key>ProcessType</key><string>Background</string>\n<key>StandardOutPath</key><string>${xmlEscape(macLogFile)}</string>\n<key>StandardErrorPath</key><string>${xmlEscape(macLogFile)}</string>\n</dict></plist>\n`;
+  fs.writeFileSync(macServiceFile, plist, { mode: 0o600 });
+  spawnSync('launchctl', ['bootout', domain, macServiceFile], { stdio: 'ignore' });
+  run('launchctl', ['bootstrap', domain, macServiceFile]);
+  run('launchctl', ['enable', target]);
+  run('launchctl', ['kickstart', '-k', target]);
+}
+
+function installWindowsService(cliPath = globalCliPath()) {
+  const command = `"${cliPath}" start`;
+  run('schtasks.exe', ['/Create', '/TN', windowsTaskName, '/TR', command, '/SC', 'ONLOGON', '/RL', 'LIMITED', '/F']);
+  run('schtasks.exe', ['/Run', '/TN', windowsTaskName]);
+}
+
 function installPersistentAgent(config) {
-  if (process.platform !== 'linux') throw new Error('Automatic background service installation currently supports Linux');
+  const platform = servicePlatform();
+  if (!['linux', 'darwin', 'win32'].includes(platform)) throw new Error(`Automatic background service installation is not supported on ${platform}`);
   console.log(`Installing ReMCP ${VERSION}…`);
   npmGlobalInstall(`${PACKAGE_NAME}@${VERSION}`, config.runtime.packageSpec);
-  installLinuxService(globalCliPath());
-  console.log('ReMCP is installed as a user service. Future updates: remcp update');
+  const cliPath = globalCliPath();
+  if (platform === 'linux') installLinuxService(cliPath);
+  else if (platform === 'darwin') installMacService(cliPath);
+  else installWindowsService(cliPath);
+  console.log('ReMCP is installed as a background service. Future updates: remcp update');
 }
 
-function restartLinuxServiceIfInstalled() {
-  if (process.platform !== 'linux' || !fs.existsSync(serviceFile)) return;
-  run('systemctl', ['--user', 'daemon-reload']);
-  run('systemctl', ['--user', 'restart', 'remcp-agent.service']);
+function restartPersistentServiceIfInstalled() {
+  const platform = servicePlatform();
+  if (platform === 'linux' && fs.existsSync(linuxServiceFile)) {
+    run('systemctl', ['--user', 'daemon-reload']);
+    run('systemctl', ['--user', 'restart', 'remcp-agent.service']);
+  } else if (platform === 'darwin' && fs.existsSync(macServiceFile)) {
+    run('launchctl', ['kickstart', '-k', `${macLaunchDomain()}/${macServiceLabel}`]);
+  } else if (platform === 'win32') {
+    const result = spawnSync('schtasks.exe', ['/Query', '/TN', windowsTaskName], { stdio: 'ignore' });
+    if (result.status === 0) run('schtasks.exe', ['/Run', '/TN', windowsTaskName]);
+  }
 }
 
-function uninstallLinuxService() {
-  if (process.platform !== 'linux') return;
-  spawnSync('systemctl', ['--user', 'disable', '--now', 'remcp-agent.service'], { stdio: 'inherit' });
-  try { fs.unlinkSync(serviceFile); } catch {}
-  spawnSync('systemctl', ['--user', 'daemon-reload'], { stdio: 'inherit' });
+function uninstallPersistentService() {
+  const platform = servicePlatform();
+  if (platform === 'linux') {
+    spawnSync('systemctl', ['--user', 'disable', '--now', 'remcp-agent.service'], { stdio: 'inherit' });
+    try { fs.unlinkSync(linuxServiceFile); } catch {}
+    spawnSync('systemctl', ['--user', 'daemon-reload'], { stdio: 'inherit' });
+  } else if (platform === 'darwin') {
+    const domain = macLaunchDomain();
+    spawnSync('launchctl', ['bootout', domain, macServiceFile], { stdio: 'ignore' });
+    try { fs.unlinkSync(macServiceFile); } catch {}
+  } else if (platform === 'win32') {
+    spawnSync('schtasks.exe', ['/End', '/TN', windowsTaskName], { stdio: 'ignore' });
+    spawnSync('schtasks.exe', ['/Delete', '/TN', windowsTaskName, '/F'], { stdio: 'ignore' });
+  }
 }
 
 function assertRuntimeTrust(server, flags) {
@@ -109,11 +230,11 @@ function assertRuntimeTrust(server, flags) {
 }
 
 function printHelp() {
-  console.log(`ReMCP ${VERSION}\n\nCommands:\n  remcp start\n  remcp status\n  remcp doctor\n  remcp update\n  remcp install\n  remcp uninstall\n  remcp uninstall --purge\n  remcp --version\n\nPairing commands are generated in the ReMCP workspace.`);
+  console.log(`ReMCP ${VERSION}\n\nCommands:\n  remcp start\n  remcp status\n  remcp doctor\n  remcp update\n  remcp install\n  remcp uninstall\n  remcp uninstall --purge\n  remcp telemetry [status|on|off]\n  remcp --version\n\nPairing commands are generated in the ReMCP workspace.\n\nUsage metrics are opt-out (tool names, timings, outcomes only, sent to your own ReMCP\naccount through the paired agent). Disable them at any time with: remcp telemetry off`);
 }
 
 export async function main(argv = process.argv.slice(2)) {
-  const { command, flags } = parse(argv);
+  const { command, flags, positional } = parse(argv);
 
   if (command === '--version' || command === '-v' || command === 'version') {
     console.log(VERSION);
@@ -128,7 +249,7 @@ export async function main(argv = process.argv.slice(2)) {
     const response = await fetch(`${server}/api/pair/claim`, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ code, name: String(flags.name || os.hostname()), hostname: os.hostname(), platform: process.platform, arch: process.arch }),
+      body: JSON.stringify({ code, machineId: ensureMachineId(), name: String(flags.name || os.hostname()), hostname: os.hostname(), platform: process.platform, arch: process.arch }),
     });
     if (!response.ok) throw new Error(`Pairing failed (${response.status}): ${await response.text()}`);
     const paired = await response.json();
@@ -138,6 +259,7 @@ export async function main(argv = process.argv.slice(2)) {
       deviceToken: paired.deviceToken,
       deviceName: String(flags.name || os.hostname()),
       runtime: normalizeRuntime(paired.runtime),
+      machineId: ensureMachineId(),
     };
     saveConfig(config);
     console.log(`Paired ${os.hostname()} with ${server}`);
@@ -146,14 +268,43 @@ export async function main(argv = process.argv.slice(2)) {
   }
 
   if (command === 'start') {
-    await runAgent(loadConfig());
+    const cfg = loadConfig();
+    const telemetry = telemetryState();
+    await runAgent({
+      ...cfg,
+      telemetryEnabled: telemetry.enabled,
+      installReported: telemetry.installReported,
+      installSpec: `${PACKAGE_NAME}@${VERSION}`,
+      persistState: patch => saveConfig({ ...cfg, ...patch }),
+    });
     return;
   }
 
+  if (command === 'telemetry') {
+    const action = String(positional[0] || 'status').toLowerCase();
+    if (action === 'status') {
+      console.log(JSON.stringify(telemetryState(), null, 2));
+      return;
+    }
+    if (action === 'on' || action === 'enable') {
+      console.log(JSON.stringify(setTelemetry(true), null, 2));
+      restartPersistentServiceIfInstalled();
+      console.log('Usage metrics enabled and the agent restarted to apply it.');
+      return;
+    }
+    if (action === 'off' || action === 'disable') {
+      console.log(JSON.stringify(setTelemetry(false), null, 2));
+      restartPersistentServiceIfInstalled();
+      console.log('Usage metrics disabled and the agent restarted to apply it.');
+      return;
+    }
+    throw new Error('Usage: remcp telemetry [status|on|off]');
+  }
+
   if (command === 'status' || command === 'doctor') {
     const cfg = loadConfig();
     const health = await fetch(`${cfg.serverUrl}/health?fresh=${Date.now()}`, { cache: 'no-store' }).then(r => r.json());
-    console.log(JSON.stringify({ configured: true, cliVersion: VERSION, deviceId: cfg.deviceId, deviceName: cfg.deviceName, server: cfg.serverUrl, serverHealth: health }, null, 2));
+    console.log(JSON.stringify({ configured: true, cliVersion: VERSION, deviceId: cfg.deviceId, deviceName: cfg.deviceName, server: cfg.serverUrl, runtime: cfg.runtime, telemetry: telemetryState(), serverHealth: health }, null, 2));
     return;
   }
 
@@ -166,13 +317,13 @@ export async function main(argv = process.argv.slice(2)) {
     const cfg = loadConfig();
     console.log('Updating ReMCP to the latest published version…');
     npmGlobalInstall(`${PACKAGE_NAME}@latest`, cfg.runtime.packageSpec);
-    restartLinuxServiceIfInstalled();
+    restartPersistentServiceIfInstalled();
     console.log('ReMCP updated. Run `remcp --version` or `remcp status` to verify.');
     return;
   }
 
   if (command === 'uninstall') {
-    uninstallLinuxService();
+    uninstallPersistentService();
     if (flags.purge) {
       const cfg = loadConfig(false);
       const specs = [PACKAGE_NAME, ...(cfg?.runtime?.packageName ? [cfg.runtime.packageName] : [])];

package/src/version.mjs

@@ -2,5 +2,5 @@ import { readFileSync } from 'node:fs';
 
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 
-export const PACKAGE_NAME = pkg.name;
+export const PACKAGE_NAME = '@remcp/remcp';
 export const VERSION = pkg.version;