Updating

gensparx is moving fast (pre “1.0”). Treat updates like shipping infra: update → run checks → restart (or use gensparx 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 gensparx doctor when needed.

curl -fsSL https://gensparx.com/install.sh | bash

Notes:

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

For source installs, use:

curl -fsSL https://gensparx.com/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 gensparx@latest under the hood.
Legacy note: compatibility shims for older CLI names remain available.

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: ~/.gensparx/gensparx.json
- Credentials: ~/.gensparx/credentials/
- Workspace: ~/.gensparx/workspace

Update (global install)

Global install (pick one):

npm i -g gensparx@latest

pnpm add -g gensparx@latest

We do not recommend Bun for the Gateway runtime (WhatsApp/Telegram bugs). To switch update channels (git + npm installs):

gensparx update --channel beta
gensparx update --channel dev
gensparx 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, gensparx 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 gensparx update.

Use gensparx update --dry-run to preview update actions before enabling automation. Then:

gensparx doctor
gensparx gateway restart
gensparx health

Notes:

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

Update (`gensparx update`)

For source installs (git checkout), prefer:

gensparx 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 gensparx doctor.
Restarts the gateway by default (use --no-restart to skip).

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

Runs the same source-update flow as gensparx update (git checkout only).
Writes a restart sentinel with a structured report (stdout/stderr tail).
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:

gensparx update

Manual (equivalent-ish):

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

Notes:

pnpm build matters when you run the packaged gensparx binary (gensparx.mjs) or use Node to run dist/.
If you run from a repo checkout without a global install, use pnpm gensparx ... for CLI commands.
If you run directly from TypeScript (pnpm gensparx ...), 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 gensparx doctor so the gateway service entrypoint is rewritten to the current install.

Always Run: `gensparx doctor`

Doctor is the “safe update” command. It’s intentionally boring: repair + migrate + warn. Note: if you’re on a source install (git checkout), gensparx doctor will offer to run gensparx 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 gensparx services.
On Linux, ensure systemd user lingering (so the Gateway survives logout).

Details: Doctor

Start / stop / restart the Gateway

CLI (works regardless of OS):

gensparx gateway status
gensparx gateway stop
gensparx gateway restart
gensparx gateway --port 18789
gensparx logs --follow

If you’re supervised:

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

npm i -g gensparx@<version>

pnpm add -g gensparx@<version>

Tip: to see the current published version, run npm view gensparx version. Then restart + re-run doctor:

gensparx doctor
gensparx gateway restart

Pin (source) by date

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

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

Then reinstall deps + restart:

pnpm install
pnpm build
gensparx gateway restart

If you want to go back to latest later:

git checkout main
git pull

If you’re stuck

Run gensparx doctor again and read the output carefully (it often tells you the fix).
Check: Troubleshooting
Ask in Discord: https://docs.gensparx.com/help/faq

Install overview

Install methods

Maintenance

Advanced

Updating

Updating

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

Before you update

Update (global install)

Core auto-updater (optional)

Update (`gensparx update`)

Update (Control UI / RPC)

Update (from source)

Always Run: `gensparx doctor`

Start / stop / restart the Gateway

Rollback / pinning (when something breaks)

Pin (global install)

Pin (source) by date

If you’re stuck

​Updating

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

​Before you update

​Update (global install)

​Core auto-updater (optional)

​Update (gensparx update)

​Update (Control UI / RPC)

​Update (from source)

​Always Run: gensparx doctor

​Start / stop / restart the Gateway

​Rollback / pinning (when something breaks)

​Pin (global install)

​Pin (source) by date

​If you’re stuck

Updating

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

Before you update

Update (global install)

Core auto-updater (optional)

Update (`gensparx update`)

Update (Control UI / RPC)

Update (from source)

Always Run: `gensparx doctor`

Start / stop / restart the Gateway

Rollback / pinning (when something breaks)

Pin (global install)

Pin (source) by date

If you’re stuck