Upgrading from 4.x? 5.x needs Node 22.14+ or 24+; Node 20 and 23 are unsupported. On Node 20, npm warns and still installs unless engine-strict is set; the database engine will not load. Read the guide.
Upgrading to ShieldCortex 5.0
Read this before you run npm install -g shieldcortex. 5.x is a breaking release. npm latest is 5.20.0. On Node 20, npm warns (EBADENGINE) and installs anyway; with engine-strict it refuses. The native module will not load.
Should I update?
Run node -v, then:
- 22.14 or newer 22.x — fine. Install 5.0.
- 24.x — fine. This is the line 5.0 was built to un-break.
- 20.x — unsupported. npm warns and installs anyway unless
engine-strictis on, in which case it refuses. The database engine will not load: the install-time check prints a warning (it does not stop the install) andshieldcortex doctorreports the Node runtime as FAIL. Upgrade Node first, or stay on 4.54.15 withnpm install -g shieldcortex@4. - 23.x — not supported (never was). Use 22 LTS or 24.
What breaks
That is the whole list.
- Node 20 is gone. The database engine moved to better-sqlite3 13, which needs Node-API 10. Node 20 does not have it.
- Node 23 is not supported. Same reason.
- Three Express 5 behaviour changes for anyone calling the dashboard HTTP API directly (scripts, curl, integrations). The dashboard UI itself is unaffected. Nested bracket query strings, empty JSON bodies, and unhandled errors all change. Details are in the full upgrade notes.
What is not breaking, but you should know
- Action Guard stays off by default. 4.54.15 already did this. 5.0 does not turn it back on. Existing hosts with
actionGuard.enabled: truestay on. - Automatic memory-injection scanning stays off.
Step by step
cp -a ~/.shieldcortex ~/.shieldcortex.bak-$(date +%Y%m%d)
node -v # must be 22.14+ or 24
npm install -g shieldcortex@5
shieldcortex doctor
Schema migrations are forward-only. We have not verified that a 5.0 database opens cleanly in 4.x — back up first.
Stay on 4.x / roll back
npm install -g shieldcortex@4 # last 4.x is 4.54.15
npm install -g shieldcortex installs 5.20.0. Pin shieldcortex@4.54.15 if you do not want 5.x the next time you type @latest.
Canonical notes (also ships inside the npm package): docs/UPGRADING-5.md.