Skip to content
RemoteClaw

Updating

Updating

RemoteClaw is moving fast (pre “1.0”). Treat updates like shipping infra: update → run checks → restart (or use remoteclaw update, which restarts) → verify.

The preferred update path is to re-run the installer from the website. It detects existing installs, upgrades in place, and runs remoteclaw doctor when needed.

Terminal window
curl -fsSL https://remoteclaw.org/install.sh | bash

Notes:

  • Add --no-onboard if you don’t want the onboarding wizard to run again.

  • For source installs, use:

    Terminal window
    curl -fsSL https://remoteclaw.org/install.sh | bash -s -- --install-method git --no-onboard

    The installer will git pull --rebase only if the repo is clean.

  • For global installs, the script uses npm install -g remoteclaw@latest under the hood.

  • Legacy note: clawdbot remains available as a compatibility shim.

Before you update

  • Know how you installed: global (npm/pnpm) vs from source (git clone).
  • Know how your Gateway is running: foreground terminal vs supervised service (launchd/systemd).
  • Snapshot your tailoring:
    • Config: ~/.remoteclaw/remoteclaw.json
    • Credentials: ~/.remoteclaw/credentials/
    • Workspace: ~/.remoteclaw/workspace

Update (global install)

Global install (pick one):

Terminal window
npm i -g remoteclaw@latest
Terminal window
pnpm add -g remoteclaw@latest

We do not recommend Bun for the Gateway runtime (WhatsApp/Telegram bugs).

To switch update channels (git + npm installs):

Terminal window
remoteclaw update --channel beta
remoteclaw update --channel dev
remoteclaw update --channel stable

Use --tag <dist-tag|version> for a one-off install tag/version.

See Development channels for channel semantics and release notes.

Note: on npm installs, the gateway logs an update hint on startup (checks the current channel tag). Disable via update.checkOnStart: false.

Core auto-updater (optional)

Auto-updater is off by default and is a core Gateway feature (not a plugin).

{
  "update": {
    "channel": "stable",
    "auto": {
      "enabled": true,
      "stableDelayHours": 6,
      "stableJitterHours": 12,
      "betaCheckIntervalHours": 1
    }
  }
}

Behavior:

  • stable: when a new version is seen, RemoteClaw waits stableDelayHours and then applies a deterministic per-install jitter in stableJitterHours (spread rollout).
  • beta: checks on betaCheckIntervalHours cadence (default: hourly) and applies when an update is available.
  • dev: no automatic apply; use manual remoteclaw update.

Use remoteclaw update --dry-run to preview update actions before enabling automation.

Then:

Terminal window
remoteclaw doctor
remoteclaw gateway restart
remoteclaw health

Notes:

  • If your Gateway runs as a service, remoteclaw gateway restart is preferred over killing PIDs.
  • If you’re pinned to a specific version, see “Rollback / pinning” below.

Update (remoteclaw update)

For source installs (git checkout), prefer:

Terminal window
remoteclaw update

It runs a safe-ish update flow:

  • Requires a clean worktree.
  • Switches to the selected channel (tag or branch).
  • Fetches + rebases against the configured upstream (dev channel).
  • Installs deps, builds, builds the Control UI, and runs remoteclaw doctor.
  • Restarts the gateway by default (use --no-restart to skip).

If you installed via npm/pnpm (no git metadata), remoteclaw update will try to update via your package manager. If it can’t detect the install, use “Update (global install)” instead.

Update (Control UI / RPC)

The Control UI has Update & Restart (RPC: update.run). It:

  1. Runs the same source-update flow as remoteclaw update (git checkout only).
  2. Writes a restart sentinel with a structured report (stdout/stderr tail).
  3. Restarts the gateway and pings the last active session with the report.

If the rebase fails, the gateway aborts and restarts without applying the update.

Update (from source)

From the repo checkout:

Preferred:

Terminal window
remoteclaw update

Manual (equivalent-ish):

Terminal window
git pull
pnpm install
pnpm build
pnpm ui:build # auto-installs UI deps on first run
remoteclaw doctor
remoteclaw health

Notes:

  • pnpm build matters when you run the packaged remoteclaw binary (remoteclaw.mjs) or use Node to run dist/.
  • If you run from a repo checkout without a global install, use pnpm remoteclaw ... for CLI commands.
  • If you run directly from TypeScript (pnpm remoteclaw ...), a rebuild is usually unnecessary, but config migrations still apply → run doctor.
  • Switching between global and git installs is easy: install the other flavor, then run remoteclaw doctor so the gateway service entrypoint is rewritten to the current install.

Always Run: remoteclaw doctor

Doctor is the “safe update” command. It’s intentionally boring: repair + migrate + warn.

Note: if you’re on a source install (git checkout), remoteclaw doctor will offer to run remoteclaw update first.

Typical things it does:

  • Migrate deprecated config keys / legacy config file locations.
  • Audit DM policies and warn on risky “open” settings.
  • Check Gateway health and can offer to restart.
  • Detect and migrate older gateway services (launchd/systemd; legacy schtasks) to current RemoteClaw services.
  • On Linux, ensure systemd user lingering (so the Gateway survives logout).

Details: Doctor

Start / stop / restart the Gateway

CLI (works regardless of OS):

Terminal window
remoteclaw gateway status
remoteclaw gateway stop
remoteclaw gateway restart
remoteclaw gateway --port 18789
remoteclaw logs --follow

If you’re supervised:

  • macOS launchd (app-bundled LaunchAgent): launchctl kickstart -k gui/$UID/ai.remoteclaw.gateway (use ai.remoteclaw.<profile>; legacy com.remoteclaw.* still works)
  • Linux systemd user service: systemctl --user restart remoteclaw-gateway[-<profile>].service
  • Windows (WSL2): systemctl --user restart remoteclaw-gateway[-<profile>].service
    • launchctl/systemctl only work if the service is installed; otherwise run remoteclaw gateway install.

Runbook + exact service labels: Gateway runbook

Rollback / pinning (when something breaks)

Pin (global install)

Install a known-good version (replace <version> with the last working one):

Terminal window
npm i -g remoteclaw@<version>
Terminal window
pnpm add -g remoteclaw@<version>

Tip: to see the current published version, run npm view remoteclaw version.

Then restart + re-run doctor:

Terminal window
remoteclaw doctor
remoteclaw gateway restart

Pin (source) by date

Pick a commit from a date (example: “state of main as of 2026-01-01”):

Terminal window
git fetch origin
git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"

Then reinstall deps + restart:

Terminal window
pnpm install
pnpm build
remoteclaw gateway restart

If you want to go back to latest later:

Terminal window
git checkout main
git pull

If you’re stuck