ds-harness-remote-fast/docs/installation.md

11 KiB

Remote plugin installation

简体中文

The sole installer is scripts/install.sh. There are no Windows, separate uninstall or token-wrapper scripts.

Online updates in DSH Plugin management

Starting with DSH 0.2.2, Remote installed from npm can check for versions and update under Extensions / Plugin management → ds-harness-remote. The official DSH plugin manager owns the update. With hot reload, it stops the old version before installing the new one and attempts to restore the previous version if installation fails or is cancelled. Restoration can also fail; check the final result in Plugin management and restart when requested.

GitHub, local directory, file: and link: installations are not eligible for official online updates. To switch to npm, use the same Desktop's official dsh launcher:

dsh plugin --profile desktop add -w ds-harness-remote@latest

For a Web Host, use its actual launcher, DSH_HOME and profile (usually web). Restart when requested after switching sources, then check versions in Plugin management. Keep the profile and Remote credential directory.

The local Remote dialog offers an update only after its registry check finds a newer version and official Plugin management marks the installation updatable. Other sources retain a release link. Updating Remote interrupts its connections; operate locally. Before upgrade or downgrade, stop every Harness process and back up profiles and credentials; see the integration guide.

Linux: DSH, one-time registration and boot startup

Linux requires root. The system service runs as root, so Remote Host, Agent tools and remote terminals also have root privileges. Only grant access to trusted accounts. This installer currently does not configure a non-root service user.

Install

Download and inspect the script first. This example reads the token privately inside a root shell rather than putting it in command arguments or shell history:

curl -fsSL https://dsh.r2049.cn/app/install.sh -o install.sh
# Inspect the downloaded script before running:
sudo -H bash -c '
  read -r -s -p "One-time Host registration token: " token; printf "\n"
  DSH_REMOTE_REGISTRATION_TOKEN="$token" bash ./install.sh
'

Omit sudo -H when already in a root shell. For a repository checkout, replace ./install.sh with ./scripts/install.sh. Repository changes are not automatically deployed to the hosted endpoint; confirm your downloaded script includes the full Linux flow.

The installer:

  1. Reuses DSH_COMMAND or an existing DSH on PATH without upgrading it.
  2. If absent, installs official Node.js 24.9.0, DSH and private pnpm 9.15.4 under /opt/ds-harness-remote/runtime.*. The Node.js archive is pinned to the official SHA-256 checksums. The stable launcher is /opt/ds-harness-remote/bin/dsh, reused on subsequent runs.
  3. Installs/updates Remote using official dsh plugin management, defaulting to the web profile and npm latest.
  4. If a token is supplied, exchanges it through the existing Host registration-code API and persists device credentials. The token is not written to logs, service configuration or persistent device-credential fields. It is not a model API key.
  5. Verifies the profile has an active official Web Host startup, configures a systemd system service, enables boot startup, and starts/restarts the matching installer-managed instance. No login or linger is needed.

It does not change system Node.js, global PATH or npm configuration, or install OS dependencies through apt/yum. Initial bootstrap requires Linux x64/arm64 with libraries compatible with official Node.js binaries, plus existing curl, tar and sha256sum. Automatic services require a working systemd system manager; use DSH_REMOTE_AUTOSTART=0 in non-systemd containers to skip service setup.

Without a token, registration is skipped; sign in through Remote later. A running service does not mean the Host is authorized or online. Network access, occupied ports and model-provider configuration can also affect initial operation.

Inspect the service

For the default profile:

sudo systemctl status ds-harness-remote-web.service
sudo systemctl is-enabled ds-harness-remote-web.service

Web binds only to 127.0.0.1. The installer checks systemd process state, not end-to-end Host availability in a client.

Reinstallation and safety

Remote credentials live under $DSH_HOME/ds-harness-remote (default ~/.dsh/ds-harness-remote). Installation credential setup and the first startup after an upgrade automatically move the old remote directory before reading or creating credentials. No manual migration command or re-pairing is needed.

Before moving, migration verifies the known Remote layout, device key pairs, trusted-peer fingerprints, credential device IDs and Server scope hashes. Unknown files or inconsistent records stop migration; a directory name alone is not treated as proof of ownership. The entire directory moves together, retaining identities, Server scopes, tokens and trusted peers.

If a verified directory cannot be moved because of permissions, a busy filesystem or a filesystem boundary, Remote records the fallback choice outside the credential tree, and this and subsequent processes continue using the same legacy directory. It does not create replacement identities or clear authorization. If this record cannot be saved, startup stops without changing credentials. This fallback requires the original directory to remain intact and the destination to remain absent. Stop old Harness instances as part of upgrading/restarting; if both directories exist, or locks or symlinks are found, migration stops without merging or overwriting credentials.

Older installer releases used /opt/dsh-remote and dsh-remote-<profile>.service. These names are not automatically migrated. The installer refuses to proceed if an owned legacy service is still active or enabled. Before reinstalling with the new defaults, stop and disable the old service (for the default profile: sudo systemctl disable --now dsh-remote-web.service). Old dsh-remote settings are no longer imported; configure Remote again after reinstalling.

  • Routine updates do not need another token. A consumed one-time token cannot be reused.
  • Existing Host credentials are never silently replaced. Stop the original Host and sign out through official controls before changing accounts with a fresh token.
  • If registration succeeds but service startup fails, credentials remain. Repair the environment and rerun without a token.
  • Units carry a canonical DSH_HOME ownership marker. Only matching installer-managed units are updated. Different homes, unmarked legacy units and symlinks are not taken over.
  • Web capability and unit ownership are preflighted before token redemption. Headless, SDK and terminal-only profiles (including dsh-tui) do not get Web units; use DSH_REMOTE_AUTOSTART=0 and manage those processes separately. For TUI profiles, install the matching standalone ds-harness-remote-tui bundle; enable only one Remote Host entry.
  • Only matching managed services are started/restarted. Other DSH processes are not stopped automatically; exit old foreground processes using the same home to prevent connection replacement or port conflicts.
  • Legacy services and runtimes are not migrated or deleted. Credentials are retained and their directory migration follows the rules above. There is no automatic rollback; failed bootstrap directories may remain for inspection.

macOS: reuse Desktop / CLI

Run as a normal user:

curl -fsSL https://dsh.r2049.cn/app/install.sh | bash

The installer prefers Desktop's official launcher under ~/Applications or /Applications, otherwise dsh on PATH. Both present is valid; neither present fails. It does not install Desktop, DSH or Node.js, or create services.

Desktop defaults to desktop; standalone CLI defaults to web. Override with DSH_COMMAND / DSH_PROFILE. Token registration uses the same installer; restart the selected Desktop/CLI manually afterward. Without a token, sign in through Remote or the standalone ds-harness-remote login CLI.

Alternatively, open Desktop Extensions / Plugin management and install from npm:

ds-harness-remote@0.6.5

An ordinary standalone CLI cannot manage the reserved desktop profile; use Desktop's official launcher.

Options and environment

Setting Meaning
DSH_COMMAND Existing launcher; an invalid explicit selection fails rather than switching instances
DSH_PROFILE Selected profile; standalone defaults to web, Desktop to desktop
DSH_HOME Existing value is preserved; registration and runtime share one home, usually root's .dsh on Linux
REMOTE_VERSION Remote release, default npm latest
INTELLIGENT_UI 1 also installs the Intelligent UI companion into the same profile; default 0
INTELLIGENT_UI_VERSION Intelligent UI release when INTELLIGENT_UI=1, default npm latest
DSH_VERSION New Linux DSH installation version, default npm latest; does not upgrade an existing DSH
DSH_REMOTE_REGISTRATION_TOKEN One-time Host token; private interactive input is recommended
DSH_REMOTE_AUTOSTART=0 Skip Linux service setup/start; root is still required
DSH_INSTALL_ROOT Linux private bootstrap root, default /opt/ds-harness-remote; absolute path required
DSH_SYSTEMD_DIR System unit directory, default /etc/systemd/system; leave unchanged for ordinary deployments

bash install.sh --token '<one-time-token>' and a positional token are also accepted, but may expose it through process listings or shell history. Do not use shell tracing/debugging with credentials. Invalid, expired or consumed tokens fail registration.

Stop and remove

Disable the Linux system service first, replacing web with the actual profile:

sudo systemctl disable --now ds-harness-remote-web.service

Then use the same launcher, profile and DSH_HOME with official plugin removal. For the default newly bootstrapped launcher:

sudo -H /opt/ds-harness-remote/bin/dsh plugin --profile web remove -w ds-harness-remote

Use Desktop Plugin management on Desktop. Runtime directories, profiles, device credentials and unit files are not automatically deleted. Windows users can still use official Plugin management or an existing Harness CLI, but no Windows installer is maintained here.

Download source and validation limits

If the domain is unavailable, replace https://dsh.r2049.cn/app with https://raw.githubusercontent.com/liguobao/ds-harness-remote/main/scripts.

Smoke checks with mocked downloads/systemctl and temporary target directories are not clean-server installation, production token redemption or reboot acceptance. Verify the service on the target server and confirm the Host is online in a client. Repository updates do not deploy hosted scripts automatically.