> ## Documentation Index
> Fetch the complete documentation index at: https://aiwithapex.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Updating

# Updating

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

## Recommended: re-run the website installer (upgrade in place)

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

```bash theme={null}
curl -fsSL https://github.com/moshehbenavraham/crocbot/install.sh | bash
```

Notes:

* Add `--no-onboard` if you don’t want the onboarding wizard to run again.
* For **source installs**, use:
  ```bash theme={null}
  curl -fsSL https://github.com/moshehbenavraham/crocbot/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 crocbot@latest` under the hood.
* Legacy note: `crocbot` 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: `~/.crocbot/crocbot.json`
  * Credentials: `~/.crocbot/credentials/`
  * Workspace: `~/croc`

## Update (global install)

Global install (pick one):

```bash theme={null}
npm i -g crocbot@latest
```

```bash theme={null}
pnpm add -g crocbot@latest
```

Note: **Node** is the recommended Gateway runtime.

To switch update channels (git + npm installs):

```bash theme={null}
crocbot update --channel beta
crocbot update --channel dev
crocbot update --channel stable
```

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

See [Development channels](/install/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`.

Then:

```bash theme={null}
crocbot doctor
crocbot gateway restart
crocbot health
```

Notes:

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

## Update (`crocbot update`)

For **source installs** (git checkout), prefer:

```bash theme={null}
crocbot 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 `crocbot doctor`.
* Restarts the gateway by default (use `--no-restart` to skip).

If you installed via **npm/pnpm** (no git metadata), `crocbot 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 `crocbot 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:

```bash theme={null}
crocbot update
```

Manual (equivalent-ish):

```bash theme={null}
git pull
pnpm install
pnpm build
pnpm ui:build # auto-installs UI deps on first run
crocbot doctor
crocbot health
```

Notes:

* `pnpm build` matters when you run the packaged `crocbot` binary ([`dist/entry.js`](https://github.com/moshehbenavraham/crocbot/blob/main/dist/entry.js)) or use Node to run `dist/`.
* If you run from a repo checkout without a global install, use `pnpm crocbot ...` for CLI commands.
* If you run directly from TypeScript (`pnpm crocbot ...`), 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 `crocbot doctor` so the gateway service entrypoint is rewritten to the current install.

## Always Run: `crocbot doctor`

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

Note: if you’re on a **source install** (git checkout), `crocbot doctor` will offer to run `crocbot 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 crocbot services.
* On Linux, ensure systemd user lingering (so the Gateway survives logout).

Details: [Doctor](/gateway/doctor)

## Start / stop / restart the Gateway

CLI (works regardless of OS):

```bash theme={null}
crocbot gateway status
crocbot gateway stop
crocbot gateway restart
crocbot gateway --port 18789
crocbot logs --follow
```

If you’re supervised:

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

Runbook + exact service labels: [Gateway runbook](/gateway)

## Rollback / pinning (when something breaks)

### Pin (global install)

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

```bash theme={null}
npm i -g crocbot@<version>
```

```bash theme={null}
pnpm add -g crocbot@<version>
```

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

Then restart + re-run doctor:

```bash theme={null}
crocbot doctor
crocbot gateway restart
```

### Pin (source) by date

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

```bash theme={null}
git fetch origin
git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"
```

Then reinstall deps + restart:

```bash theme={null}
pnpm install
pnpm build
crocbot gateway restart
```

If you want to go back to latest later:

```bash theme={null}
git checkout main
git pull
```

## If you’re stuck

* Run `crocbot doctor` again and read the output carefully (it often tells you the fix).
* Check: [Troubleshooting](/gateway/troubleshooting)
* Check: [FAQ](/help/faq)