Genesis Docs

System requirements

  • Node 24 (recommended) or Node 22.14+ — the installer script handles this automatically
  • macOS, Linux, or Windows — both native Windows and WSL2 are supported; WSL2 is more stable. See Windows.
  • pnpm is only needed if you build from source

Recommended: installer script

The fastest way to install. It detects your OS, installs Node if needed, installs Genesis, and launches onboarding.

macOS / Linux / WSL2

```bash
curl -fsSL https://genesis.pixelzx.com/install.sh | bash
```

Windows (PowerShell)

```powershell
iwr -useb https://genesis.pixelzx.com/install.ps1 | iex
```

To install without running onboarding:

macOS / Linux / WSL2

```bash
curl -fsSL https://genesis.pixelzx.com/install.sh | bash -s -- --no-onboard
```

Windows (PowerShell)

```powershell
& ([scriptblock]::Create((iwr -useb https://genesis.pixelzx.com/install.ps1))) -NoOnboard
```

For all flags and CI/automation options, see Installer internals.

Alternative install methods

Local prefix installer (install-cli.sh)

Use this when you want Genesis and Node kept under a local prefix such as ~/.genesis, without depending on a system-wide Node install:

curl -fsSL https://genesis.pixelzx.com/install-cli.sh | bash

It supports npm installs by default, plus git-checkout installs under the same prefix flow. Full reference: Installer internals.

npm, pnpm, or bun

If you already manage Node yourself:

npm

```bash
npm install -g @pixelzx/genesis@latest
genesis onboard --install-daemon
```

pnpm

```bash
pnpm add -g @pixelzx/genesis@latest
pnpm approve-builds -g
genesis onboard --install-daemon
```

<div class="callout note">
pnpm requires explicit approval for packages with build scripts. Run `pnpm approve-builds -g` after the first install.
</div>

bun

```bash
bun add -g @pixelzx/genesis@latest
genesis onboard --install-daemon
```

<div class="callout note">
Bun is supported for the global CLI install path. For the Gateway runtime, Node remains the recommended daemon runtime.
</div>

Troubleshooting: sharp build errors (npm)

If sharp fails due to a globally installed libvips:

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g @pixelzx/genesis@latest

From source

For contributors or anyone who wants to run from a local checkout:

git clone https://github.com/PIXELZX0/Genesis.git
cd genesis
pnpm install && pnpm build && pnpm ui:build
pnpm link --global
genesis onboard --install-daemon

Or skip the link and use pnpm genesis ... from inside the repo. See Setup for full development workflows.

Install from GitHub main

npm install -g github:PIXELZX0/Genesis#main

Containers and package managers

  • Docker Containerized or headless deployments.

  • Podman Rootless container alternative to Docker.

  • Nix Declarative install via Nix flake.

  • Ansible Automated fleet provisioning.

  • Bun CLI-only usage via the Bun runtime.

Verify the install

genesis --version      # confirm the CLI is available
genesis doctor         # check for config issues
genesis gateway status # verify the Gateway is running

If you want managed startup after install:

  • macOS: LaunchAgent via genesis onboard --install-daemon or genesis gateway install
  • Linux/WSL2: systemd user service via the same commands
  • Native Windows: Scheduled Task first, with a per-user Startup-folder login item fallback if task creation is denied

Hosting and deployment

Deploy Genesis on a cloud server or VPS:

Update, migrate, or uninstall

Troubleshooting: genesis not found

If the install succeeded but genesis is not found in your terminal:

node -v           # Node installed?
npm prefix -g     # Where are global packages?
echo "$PATH"      # Is the global bin dir in PATH?

If $(npm prefix -g)/bin is not in your $PATH, add it to your shell startup file (~/.zshrc or ~/.bashrc):

export PATH="$(npm prefix -g)/bin:$PATH"

Then open a new terminal. See Node setup for more details.