UAP Device Control

Cross-platform outbound Device Control client for Universal Agent Platform.

Requirements

• Node.js 26.x (>=26.8.1 <27)
• a public UAP Device Control origin for first login
• Windows, Linux or macOS

Runner, WSL, cloudflared, a separately installed Device Agent and an inbound device port are not required for temporary npx mode.

First login

The public npm package does not embed a development, staging or production hostname. Select the intended UAP environment explicitly on first login:

npx @codingfrees/uap-device-control@latest login --origin https://<uap-device-control-origin>

The browser OAuth flow stores a device-scoped credential for that exact origin. Later commands reuse the stored origin. To change environments, logout first and then login against the other origin.

You can also provide the origin through UAP_DEVICE_CONTROL_ORIGIN.

Remote session

npx @codingfrees/uap-device-control@latest remote

The interactive CLI uses concise human-readable status lines by default (✅, ❌, ⚠️, 🔐, 🌐, 🔌, 🔧). Use --json for stable JSONL output in scripts and log collectors. Only one remote process may use a state directory at a time; starting a second process with the same device identity fails locally instead of replacing the live broker session. OAuth refresh is serialized across processes, and access-token renewal is retried in the existing broker session rather than forcing a device reconnect.

By default the Remote process also starts the loopback-only semantic browser bridge on port 8800. Until the UAP Browser Extension is paired, the CLI prints a short-lived pairing code. Browser control can be disabled with --no-browser-control or moved to another loopback port with --browser-port <port>.

If a browser extension was replaced or lost its local token, stop remote, run npx @codingfrees/uap-device-control@latest browser-reset, then start remote again. This resets only the browser pairing and preserves the device identity and login.

By default only the current directory is exposed as a Device Control filesystem root. Additional authority must be explicit:

npx @codingfrees/uap-device-control@latest remote \
  --root files=/absolute/path \
  --read-only-root archive=/absolute/archive \
  --allow-executable /absolute/path/to/executable \
  --allow-service example.service

Semantic browser control

Semantic browser control is optional and is executed by the device-control-browser companion assembly inside the generic UAP Browser Extension. It does not require Chrome/Edge remote-debugging flags or CDP.

1. Install or enable the optional device-control-browser companion in the workspace; it depends on device-control and browser-extension-host.
2. Start remote and note the local 🔐 Browser pairing code.
3. Open the UAP Browser Extension popup and the Device Control · Browser feature.
4. Enter the pairing code and bridge port shown by the CLI, then enable browser control.
5. The Remote session reconnects automatically and advertises the browser capabilities.

The browser surface supports bounded tab listing, open/navigate/activate/reload/back/forward/close, visible-page snapshot, selector-based click, bounded literal text entry and bounded vertical scrolling. Only HTTPS or loopback HTTP pages are eligible. Page content is untrusted data, no page-supplied JavaScript is evaluated, and every MCP browser tool is approval-gated.

Status

npx @codingfrees/uap-device-control@latest status

status reports the local device identity, authentication state and remote presence when authenticated.

Persistent service

After login:

npx @codingfrees/uap-device-control@latest install-service

The same runtime is persisted using the platform adapter (Windows scheduled startup, Linux systemd user service, macOS launchd).

The install-service command refuses to install a second persistent Remote if an installed Runner V2 is detected on Windows or Linux; temporary remote mode remains independent. Service installation stages the runtime atomically and retains a .previous copy for rollback if registration fails. This is not a signed automatic update channel; npm publishing and OS-service updating remain separate lifecycles.

npm client versus ChatGPT MCP

The npm client does not use MCP as its device transport. It needs the public UAP origin for OAuth and the outbound Device Control routes under /device-control/remote/*.

The /mcp endpoint is required by ChatGPT/Codex and the public OpenAI plugin listing. A production deployment may expose both surfaces from the same canonical HTTPS origin, but they are independent protocol paths and use separate OAuth scopes. The npm client uses the isolated device-control:device scope; ordinary MCP read/write tokens are rejected by the remote-device broker.

Security boundary

The client opens only outbound HTTPS connections plus the optional browser bridge bound strictly to 127.0.0.1. Filesystem roots, executable allowlists and service allowlists remain local explicit authority. Device credentials are origin-bound and cannot be silently reused against another environment. Browser pairing uses a short-lived local code, pins the exact extension ID and persists only a token hash on the Remote side; the bearer itself stays in extension storage.

Publishing

Publish a verified public release from this package with:

pnpm publish:public

Validate the exact release without publishing with pnpm publish:public -- --dry-run.

For npm whoami HTTP 401 in Linux/WSL, renew authentication locally using npm login --registry=https://registry.npmjs.org/ --auth-type=web, then confirm npm whoami. Do not paste credentials into issue reports or logs. npm versions are immutable: bump the package version and commit a clean tree before publishing.

The script requires a clean repository, refuses an already-published version, builds and dry-runs the package, then calls npm publish and verifies the registry version plus the latest dist-tag. npm account 2FA remains mandatory and is handled by npm during the publish step.