1. Requirements and installation

Use Node.js 22.19 or newer. The resolved beta version is 0.1.0-beta.16. Supported targets are macOS 12+ universal, Ubuntu Desktop 24.04 x64, and Windows 11 x64.

npm install --global @adrouter/agent@beta
adrouter-agent --version
adrouter-agent doctor --json
adrouter-agent install
adrouter-agent launch

The npm launcher downloads the matching archive from the canonical release and verifies the fixed manifest, checksum, platform, architecture, and bundle layout. Review the release notes and checksums. Current archives are ad-hoc or unsigned and are not notarized; the launcher does not disable host protections.

2. Complete platform setup

Ubuntu needs its documented Bubblewrap and secret-store packages. Windows command and Git tools require the documented one-time sandbox-runtime provisioning by the normal user with one UAC approval; the Agent does not elevate itself. Do not disable AppArmor, Gatekeeper, Windows security, or other host controls.

3. Sign in and compare the code

  1. Open the Agent and select Connect this Agent.
  2. Sign in through the authenticated AdRouter WebUI, return to the Agent, and select Continue.
  3. Compare the code displayed in both places and explicitly approve only the installation you recognize.

Official hosted access uses a protected Ed25519 installation credential; access tokens remain memory-only. Sign out and revoke the installation from Settings or the WebUI before removing the app.

4. Choose a folder and approve tools

Choose the exact project folder, then start a task. Safe reads may run quietly. Each file mutation or general command requires a fresh Allow once or Deny decision. Review paths, commands, diffs, and destinations. The app preserves pre-existing changes and shows diffs, but it does not stage, commit, push, elevate, or disable host security.

5. Update and uninstall

Update checks are available, but automatic update application is disabled in the current release. Reinstall the beta channel after reviewing the newer release and rerun doctor:

npm install --global @adrouter/agent@beta
adrouter-agent --version
adrouter-agent doctor --json
npm uninstall --global @adrouter/agent

Removing the npm launcher does not necessarily remove the managed desktop app or its local projects, chats, credentials, and preferences. First sign out/revoke and quit. Then remove the per-user app—~/Applications/AdRouter Agent.app, ${XDG_DATA_HOME:-~/.local/share}/adrouter-agent/app, or %LOCALAPPDATA%\Programs\AdRouter Agent—and remove local application data only if you intend to delete it.

Agent repositoryCompatibility update