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

# Updating

Keep FluffBuzz up to date.

## Recommended: `fluffbuzz update`

The fastest way to update. It detects your install type (npm or git), fetches the latest version, runs `fluffbuzz doctor`, and restarts the gateway.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fluffbuzz update
```

To switch channels or target a specific version:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fluffbuzz update --channel beta
fluffbuzz update --tag main
fluffbuzz update --dry-run   # preview without applying
```

`--channel beta` prefers beta, but the runtime falls back to stable/latest when
the beta tag is missing or older than the latest stable release. Use `--tag beta`
if you want the raw npm beta dist-tag for a one-off package update.

See [Development channels](/install/development-channels) for channel semantics.

## Alternative: re-run the installer

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -fsSL https://fluffbuzz.com/install.sh | bash
```

Add `--no-onboard` to skip onboarding. For source installs, pass `--install-method git --no-onboard`.

## Alternative: manual npm, pnpm, or bun

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
npm i -g fluffbuzz@latest
```

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm add -g fluffbuzz@latest
```

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
bun add -g fluffbuzz@latest
```

### Root-owned global npm installs

Some Linux npm setups install global packages under root-owned directories such as
`/usr/lib/node_modules/fluffbuzz`. FluffBuzz supports that layout: the installed
package is treated as read-only at runtime, and bundled plugin runtime
dependencies are staged into a writable runtime directory instead of mutating the
package tree.

For hardened systemd units, set a writable stage directory that is included in
`ReadWritePaths`:

```ini theme={"theme":{"light":"min-light","dark":"min-dark"}}
Environment=FLUFFBUZZ_PLUGIN_STAGE_DIR=/var/lib/fluffbuzz/plugin-runtime-deps
ReadWritePaths=/var/lib/fluffbuzz /home/fluffbuzz/.fluffbuzz /tmp
```

If `FLUFFBUZZ_PLUGIN_STAGE_DIR` is not set, FluffBuzz uses `$STATE_DIRECTORY` when
systemd provides it, then falls back to `~/.fluffbuzz/plugin-runtime-deps`.

## Auto-updater

The auto-updater is off by default. Enable it in `~/.fluffbuzz/fluffbuzz.json`:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  update: {
    channel: "stable",
    auto: {
      enabled: true,
      stableDelayHours: 6,
      stableJitterHours: 12,
      betaCheckIntervalHours: 1,
    },
  },
}
```

| Channel  | Behavior                                                                                                      |
| -------- | ------------------------------------------------------------------------------------------------------------- |
| `stable` | Waits `stableDelayHours`, then applies with deterministic jitter across `stableJitterHours` (spread rollout). |
| `beta`   | Checks every `betaCheckIntervalHours` (default: hourly) and applies immediately.                              |
| `dev`    | No automatic apply. Use `fluffbuzz update` manually.                                                          |

The gateway also logs an update hint on startup (disable with `update.checkOnStart: false`).

## After updating

<Steps>
  ### Run doctor

  ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
  fluffbuzz doctor
  ```

  Migrates config, audits DM policies, and checks gateway health. Details: [Doctor](/gateway/doctor)

  ### Restart the gateway

  ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
  fluffbuzz gateway restart
  ```

  ### Verify

  ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
  fluffbuzz health
  ```
</Steps>

## Rollback

### Pin a version (npm)

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
npm i -g fluffbuzz@<version>
fluffbuzz doctor
fluffbuzz gateway restart
```

Tip: `npm view fluffbuzz version` shows the current published version.

### Pin a commit (source)

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
git fetch origin
git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"
pnpm install && pnpm build
fluffbuzz gateway restart
```

To return to latest: `git checkout main && git pull`.

## If you are stuck

* Run `fluffbuzz doctor` again and read the output carefully.
* For `fluffbuzz update --channel dev` on source checkouts, the updater auto-bootstraps `pnpm` when needed. If you see a pnpm/corepack bootstrap error, install `pnpm` manually (or re-enable `corepack`) and rerun the update.
* Check: [Troubleshooting](/gateway/troubleshooting)
* Ask in Discord: [https://discord.gg/buzz](https://discord.gg/buzz)

## Related

* [Install Overview](/install) — all installation methods
* [Doctor](/gateway/doctor) — health checks after updates
* [Migrating](/install/migrating) — major version migration guides