Skip to main content

​
Install

Already followed Getting Started? You’re all set — this page is for alternative install methods, platform-specific instructions, and maintenance.

​
System requirements

  • Node 22+ (the installer script will install it if missing)
  • macOS, Linux, or Windows
  • pnpm only if you build from source
On Windows, we strongly recommend running gensparx under WSL2.

​
Install methods

The installer script is the recommended way to install Gensparx. It handles Node detection, installation, and onboarding in one step.
For VPS/cloud hosts, avoid third-party “1-click” marketplace images when possible. Prefer a clean base OS image (for example Ubuntu LTS), then install gensparx yourself with the installer script.

Installer script

Downloads the CLI, installs it globally via npm, and launches the onboarding wizard.
curl -fsSL https://gensparx.com/install.sh | bash
That’s it — the script handles Node detection, installation, and onboarding.To skip onboarding and just install the binary:
curl -fsSL https://gensparx.com/install.sh | bash -s -- --no-onboard
For all flags, env vars, and CI/automation options, see Installer internals.
If you already have Node 22+ and prefer to manage the install yourself:
npm install -g gensparx@latest
gensparx onboard --install-daemon
If you have libvips installed globally (common on macOS via Homebrew) and sharp fails, force prebuilt binaries:
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g gensparx@latest
If you see sharp: Please add node-gyp to your dependencies, either install build tooling (macOS: Xcode CLT + npm install -g node-gyp) or use the env var above.
For contributors or anyone who wants to run from a local checkout.
1

Clone and build

Clone the gensparx repo and build:
git clone https://github.com/gensparx/gensparx.git
cd gensparx
pnpm install
pnpm ui:build
pnpm build
2

Link the CLI

Make the gensparx command available globally:
pnpm link --global
Alternatively, skip the link and run commands via pnpm gensparx ... from inside the repo.
3

Run onboarding

gensparx onboard --install-daemon
For deeper development workflows, see Setup.

​
Other install methods

Docker and Podman are the recommended container options. Nix, Ansible, and Bun are advanced paths and may require extra validation.

Docker

Containerized or headless deployments.

Podman

Rootless container: run setup-podman.sh once, then the launch script.

Nix

Advanced: declarative install via Nix.

Ansible

Advanced: automated fleet provisioning.

Bun

Advanced: CLI-only usage via the Bun runtime.

​
After install

Verify everything is working: 
gensparx doctor         # check for config issues
gensparx status         # gateway status
gensparx dashboard      # open the browser UI
If you need custom runtime paths, use:
  • GENSPARX_HOME for home-directory based internal paths
  • GENSPARX_STATE_DIR for mutable state location
  • GENSPARX_CONFIG_PATH for config file location
See Environment vars for precedence and full details.

​
Troubleshooting: gensparx not found

Quick diagnosis:
node -v
npm -v
npm prefix -g
echo "$PATH"
If $(npm prefix -g)/bin (macOS/Linux) or $(npm prefix -g) (Windows) is not in your $PATH, your shell can’t find global npm binaries (including gensparx).Fix — add it to your shell startup file (~/.zshrc or ~/.bashrc):
export PATH="$(npm prefix -g)/bin:$PATH"
On Windows, add the output of npm prefix -g to your PATH.Then open a new terminal (or rehash in zsh / hash -r in bash).

​
Update / uninstall

Updating

Keep gensparx up to date.

Migrating

Move to a new machine.

Uninstall

Remove gensparx completely.