ProjectBridge Remote CLI
ProjectBridge is proprietary software. All rights are reserved; npm publication makes the package installable but does not grant permission to copy, modify, redistribute, or create derivative works except where separately authorized by the copyright holder.
Install and run
npx --yes @brrew/projectbridge@latest remote --server https://YOUR-BRIDGE.example
To enroll and make the host persistent in one step, run:
npx --yes @brrew/projectbridge@latest remote --persistent --server https://YOUR-BRIDGE.example
On Windows, run this from an elevated Administrator PowerShell. It installs a machine-wide agent under %ProgramData%\ProjectBridge, configures an AtStartup task running as NT AUTHORITY\SYSTEM, and does not depend on a logged-in user. Windows requires Node.js 20+ and npm for the initial installation. If Node.js is only available in the installing account, the installer stages the Node executable and npm under ProgramData so the background agent does not depend on that user profile. Existing per-user enrollment is migrated into ProgramData when possible. On macOS and Linux, persistent startup remains scoped to the installing user. The separate install-service command remains available for hosts that are already enrolled.
Remove only the persistent startup entry (the enrollment credential is retained):
npx --yes @brrew/projectbridge@latest uninstall-service
If the dashboard revoked this host, the local credential is intentionally not reusable. Start a fresh, dashboard-approved enrollment and restore persistent startup with:
npx --yes @brrew/projectbridge@latest reenroll --persistent --server https://YOUR-BRIDGE.example
The command uses the saved server when --server is omitted, stops the old background agent, requests a new one-time pairing code, and waits for you to approve the host again in the dashboard. Keep the terminal open during approval. Use reenroll without --persistent only when you want a foreground connection; use reenroll --persistent for the usual installer flow.
To fully uninstall the local agent, background startup, saved credential, and installed runtime, run:
npx --yes @brrew/projectbridge@latest uninstall --yes
Interactive runs ask for confirmation unless --yes is supplied. This removes local files only; it does not alter the host's record in the ProjectBridge dashboard. Revoke that record separately if required.
Check for and install the latest npm release into the managed runtime:
npx --yes @brrew/projectbridge@latest update
The CLI starts a short-lived enrollment request and asks you to approve the matching host in the authenticated ProjectBridge dashboard. During interactive installation, the host displays an ASCII splash screen and asks whether to allow remote tool calling (y/N, default No). Dashboard approval separately verifies and enrolls the host. The agent securely stores a host-specific credential, sends authenticated health updates, checks for authorized tasks, and reports bounded results. The persistent setup configures the agent to run in the background and reconnect after interruptions. While running, it periodically checks for updates and applies them using the package registry's secure transport and integrity checks.
Requirements
- Node.js 20+
- HTTPS access to the ProjectBridge server
- The user must be signed in to the ProjectBridge dashboard to approve the matching enrollment request
ProjectBridge does not choose a server by default. Set --server https://YOUR-BRIDGE.example on the command, or set PROJECTBRIDGE_SERVER before running it. The selected server is saved with the local enrollment. Existing enrollments keep using their saved server; passing a different --server for an already-enrolled host fails safely rather than silently redirecting it. For local development only, http://localhost:8792 is accepted. Set PROJECTBRIDGE_CONFIG to override the per-user config path; Windows machine-wide mode always uses %ProgramData%\ProjectBridge\remote.json. Requests for pairing, heartbeat, task polling, and task results go to the selected server. The agent checks npm for package updates; npm registry access is separate from the ProjectBridge server connection.
MCP tool-name compatibility
MCP tool identifiers are supplied by the ProjectBridge MCP server, which is separate from this remote host agent package. The current server uses the pb_ prefix (for example, pb_list_hosts, pb_host_task, and pb_host_system_process_terminate) to stay within MCP clients' 40-character tool-name limit. Updating this npm host-agent package does not replace the MCP server; update/restart the server installation separately.
Remote host control
On a new installation, remote tool calling defaults to disabled unless the installer explicitly answers y to the local consent prompt. Existing enrolled hosts preserve their current consent during migration and can be enabled or disabled from the dashboard with a confirmed host.control.enable / host.control.disable task:
npx --yes @brrew/projectbridge@latest remote-control status
npx --yes @brrew/projectbridge@latest remote-control enable
npx --yes @brrew/projectbridge@latest remote-control disable
When enabled, an enrolled host can provide bounded filesystem list/stat/read/search, atomic file writes and unique-text patches, directory creation, file moves/deletes, shell commands, and interactive process sessions (start/read/input/terminate). Process details and a redacted ProjectBridge config view are available too. Shell commands execute as the operating-system account running the agent, with that account's privileges; enabling host control does not elevate privileges. Mutations require confirm: true on the task. Shell output and file reads are bounded, host file reads can be resumed with byte offsets and exact Base64 chunk payloads (the hash scope is labeled as file or chunk), and directory listing/search results expose continuation cursors. File deletion refuses directories, and file patching rejects ambiguous matches. Interactive process sessions live only as long as the agent process and are not restored after restart.
The authorization state is stored in the host's enrollment config as remote_control_enabled (Windows machine-wide mode stores it under ProgramData with SYSTEM/Administrators ACLs); credentials are never returned by host.config.get. The installer’s local y opt-in enables the listed tools under the OS account running the agent; it does not elevate privileges. Dashboard approval enrolls the host but is not a substitute for that local opt-in. State-changing operations are dispatched without per-task dashboard approval once the device is enrolled and local remote control is enabled. Disable host control from the dashboard if a host should stop accepting maintenance requests. Persistent operation depends on the host's supported background-service facilities and configuration.
Optional REA tools
REA is optional and is not installed during ordinary ProjectBridge enrollment. After the ProjectBridge host is enrolled, use:
projectbridge rea status
projectbridge rea install
projectbridge rea remove
Install and remove ask for confirmation in an interactive terminal. Use --yes only when you explicitly want to approve the operation non-interactively. To opt in during initial host setup, add --with-rea to the remote or install-service command. Without that flag, the standard install remains REA-free.
The host downloads a version-pinned bundle from the authenticated ProjectBridge artifact endpoint; it does not install latest directly from npm. The server must have an approved platform bundle staged first. See the repository's docs/REA_DEPLOYMENT.md for release staging and platform requirements. REA's external analysis providers (Hopper, Ghidra, IDA, JADX, browsers and JDKs) remain separately installed optional dependencies.