Skip to main content

Installation

Most sites install GEM with a single command. The installer provisions everything GEM needs — system dependencies, PostgreSQL, a bundled Node.js runtime, and a service to keep it running — and then hands off to a browser-based setup wizard that walks you through database, ports, and notifications.

If you're a developer working from the source tree instead, see Install from Source.

Linux​

Run the installer:

wget -qO- https://updates.mygem.us/install.sh | sh

That command is a small bootstrap: it downloads the versioned installer package, verifies its SHA-256 checksum, and runs it. It starts as your normal user and elevates with sudo when needed (you may be prompted for your password) — that's why there's no sudo in the command itself. From there you'll be prompted for an install directory and the system will be provisioned (see What the installer does below) before the setup wizard opens.

Prefer to download and inspect it first?
wget -O install.sh https://updates.mygem.us/install.sh && sh install.sh

No sudo needed — the saved script self-elevates (you'll be prompted for your sudo password), and the copy you inspected is exactly what runs as root.

Windows (via WSL)​

GEM runs on Linux; on Windows it runs inside WSL. The Windows installer — a standard setup wizard — sets all of this up for you.

  1. Download and run the installer:

    https://updates.mygem.us/windows/GEM-Setup.exe

  2. When Windows SmartScreen appears, click More info → Run anyway.

  3. Approve the User Account Control (UAC) prompt and follow the wizard.

The wizard enables WSL 2, installs Ubuntu 24.04 (or lets you pick an existing WSL 2 distribution to install into), enables systemd in the distro, configures mirrored networking (so GEM is reachable on your LAN at the Windows host's IP) with no idle suspend, sets GEM to start with Windows, and then runs the same Linux installer described here inside the distro. When installation completes, it opens GEM's browser-based setup wizard for you.

A reboot may happen mid-install

Enabling WSL can require a restart. The installer resumes automatically after you sign back in — let it finish before closing any windows it opens.

What the installer does​

Before the wizard opens, the installer prepares the machine:

  1. Asks for an install directory — default /opt/gem. If the directory already exists, it offers to overwrite and backs up any existing gem.json first.
  2. Installs system dependencies via apt — including PostgreSQL, ffmpeg, nmap, arp-scan, mDNS libraries, and build tools.
  3. Starts and enables PostgreSQL.
  4. Bundles its own Node.js runtime (the exact version GEM is built against) into <install-dir>/node/, verified against Node's official checksums. GEM always uses this bundled runtime, never a system Node.
  5. Installs GEM's dependencies, then launches the setup wizard.
WSL without systemd

On WSL, if systemd isn't active the service installation step is skipped (GEM still installs and runs). To enable it, add the following to /etc/wsl.conf and restart WSL:

[boot]
systemd=true

The setup wizard​

The installer starts a local web server and opens a browser-based wizard to finish configuration. How you reach it depends on how you're installing:

  • On the machine directly (desktop session) — a browser opens automatically to the wizard.
  • Over SSH or headless — no browser is opened. The installer prints one or more URLs (on your LAN) to the terminal. Open one of them in a browser on another computer.
Use the exact URL the installer prints

The wizard is protected by a one-time session token embedded in the printed URL (...?token=...). Open that URL as-is — a URL without the token is rejected. The token is unique to this install run.

The wizard walks you through, validating each step before moving on:

  1. Preflight checks — disk space, OS version, PostgreSQL presence, and whether a GEM service already exists.
  2. Database — connection settings; the wizard can create the PostgreSQL database, user, and schema for you and build the tables. (Configures pg_hba.conf for local password auth as needed.)
  3. Web port — the port GEM serves on (default 3000); checked to be free.
  4. Time zone — detected from the system and confirmed, so schedules and history use local time.
  5. Email (SMTP) — optional; for alerts and notifications. The wizard can send a test message.
  6. SMS (Twilio) — optional; the wizard can send a test text.
  7. AI key — optional Claude API key for AI features; validated with a live check.
  8. Service — installs GEM as a systemd service (gem) and starts it. Skipped if systemd isn't available.

Everything you enter is written to gem.json (see Configuration), with secrets stored with restricted permissions.

Verify the install​

When the wizard finishes, GEM is running as a service on the port you chose. Open a browser on the same network and navigate to:

http://<server-ip>:<port>

(<port> is 3000 unless you changed it; on Windows/WSL with mirrored networking, <server-ip> is the Windows host's LAN IP.) You should see the GEM login screen.

First login

The system seeds a default administrator account on first boot. See First Boot for the credentials and the required password change.

What's next​

  • First Boot — log in and what happens on first start.
  • Quick Start — commission your first device end to end.
  • Configuration — everything the wizard wrote to gem.json, and how to change it later.

Updates​

GEM updates itself from updates.mygem.us — applied from within the running system, not by re-running the installer. Manage updates from the admin interface.