Getting started: from install to your first dashboard

choose_your_pill

Which path is yours

• A Linux server you rent or administer. Install the mod (step 1), then path A on the server itself. View the dashboard from your own computer through an SSH tunnel, covered in path A.
• A home PC running the game server, on Windows, macOS or Linux. Install the mod, then path A: the Docker Desktop variant if it is Windows or macOS, and on Linux, whichever compose file matches what you installed: the Linux one for plain Docker Engine (the usual choice), the Docker Desktop one if you specifically installed Docker Desktop for Linux instead.
• A Windows Server host, or a panel-only host with no shell access (many rented game panels are like this). Skip straight to path B, Grafana Cloud: it needs nothing installed besides the mod itself.
• The game server itself runs inside a container (a Pterodactyl panel and similar). Path A cannot reach it: 127.0.0.1 inside that container is the container, not the machine underneath it. Use path B instead.

wake_the_server

Step 1: install the mod on the server

This part is the same whichever path you pick, and it happens on the game server only, not on your own computer. Pulse needs Vintage Story 1.22 or newer.

1. Download pulse_x.x.x.zip (replace x.x.x with the version you downloaded) from the ModDB page or from GitHub releases.

   download pulse_0.2.0.zip version 0.2.0, released 2026-09-29

2. Drop the zip, unopened, into the server's Mods/ folder, the same place every other mod goes. By default that is:

   • Linux, the official server install script: /home/vintagestory/data/Mods.
   • Linux, running the server binary yourself with no --dataPath: ~/.config/VintagestoryData/Mods.
   • Windows: %AppData%\VintagestoryData\Mods (not %AppData%\Vintagestory, the install folder itself, a different place one word shorter).
   • A rented panel: wherever its file manager already shows your other mods; the panel has usually worked this out for you already.

3. Start (or restart) the server.

4. Watch the server's log for this line, which is Pulse confirming it is up:

   Logs/server-main.log

   Pulse serving metrics on http://127.0.0.1:9464/metrics

   The log is either the console you started the server in, or Logs/server-main.log next to Mods/. On a panel-only host, use whatever log view the panel gives you.

5. If you have a terminal or browser on the server itself, confirm the page it just mentioned actually answers (no shell on a panel-only host: skip this check and go straight to path B below). The address is 127.0.0.1, meaning "this machine only", so this check has to run on the server, not on your own computer. Either open http://127.0.0.1:9464/metrics in a browser running on the server, or, from a terminal on the server, run:

   shrun on the game server

   curl http://127.0.0.1:9464/metrics

   On Windows PowerShell, type curl.exe, not plain curl: PowerShell aliases curl to its own Invoke-WebRequest, which takes different options and will not behave like the command above.

   Either way you should get back plain text, a long list of lines like pulse_players_online 0. That text is what Prometheus will be reading in path A, and what the OTLP mod pushes onward in path B.

Pulse also wrote its own config file at this point, at ModConfig/pulse.json next to Mods/. You do not need to touch it for either path below.

follow_the_white_rabbit

Path A: run Prometheus and Grafana yourself

Use this path if you are happy running two small programs yourself, on your own computer or on the server.

Before you start #

• You need Docker installed. On Windows or macOS that always means Docker Desktop; see Docker's own install instructions. On Linux, that same page also offers Docker Desktop for Linux, a different product aimed at desktop use: it needs the Docker Desktop compose file below, not the plain Linux one. For the plain Linux one, install Docker Engine instead, from Docker's Engine install guide for your distribution.

• Every command below starts with docker compose (two words), which needs the current compose plugin. Installing from Docker's own repository, as the guides above do, gives you that directly. From your distribution's own repository instead, package names vary: Ubuntu calls it docker-compose-v2, and on Debian 13 (trixie) the plainly-named docker-compose package is already the current one, not the old, deprecated tool some other distributions still ship under that same name. If what you end up with only answers to a hyphenated docker-compose, the commands below work identically with a hyphen instead of a space.

• If a command below fails with "permission denied" talking to the Docker daemon, either put sudo in front of it, or add yourself to the docker group once, so future commands do not need sudo at all, following Docker's post-install steps, then log out and back in.

• You need the contrib/grafana folder from the Pulse repository:

  shrun on the game server's machine

  git clone https://github.com/StratumServer/Pulse.git
  cd Pulse/contrib/grafana

  No git on a headless server? Installing it is usually simpler than the alternative: sudo apt install git (Debian or Ubuntu) or your distribution's equivalent, then the commands above. Otherwise, on the repository's GitHub page, use Code, Download ZIP, or go straight to the repository zip. Extract it and open a terminal in the extracted contrib/grafana folder.

• The first docker compose up -d downloads the Prometheus and Grafana images, a few hundred megabytes together, so it takes minutes, not seconds. Every run after that is fast.

follow_the_white_rabbit

Path B: Grafana Cloud, if you would rather host nothing

Use this path if you do not want to run Prometheus or Grafana yourself, or your host will not let you. Grafana Cloud is Grafana's own hosted service, with a free tier: see Grafana's pricing page for the current limits (10,000 metric series, 14 day retention and 3 users, as of writing). This path needs a second, optional mod, because nobody is coming to read /metrics for you; instead, the server pushes its numbers out over the internet, using a protocol called OTLP.

Create a Grafana Cloud account yourself at grafana.com if you do not have one already.

1. In the Grafana Cloud portal at grafana.com (not the Grafana app itself), open your stack and find its OpenTelemetry tile. Click Configure, then "Generate now" (the exact wording may vary a little) to create an access policy token; it prints ready-to-use values, including OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS. Use the endpoint as printed, something like https://otlp-gateway-<region>.grafana.net/otlp.

   From OTEL_EXPORTER_OTLP_HEADERS, take everything after Authorization=, but change any %20 back into an actual space. That printed value is itself encoded for use as an environment variable; Pulse encodes header values its own way before sending them, and the exporter decodes them again once they arrive, a round trip that leaves a real space untouched, but leaves a pasted %20 exactly as pasted too, a literal %20 instead of a space, which is not the header Grafana Cloud expects. If you ever need the instance ID by itself, read it from this same OpenTelemetry tile, not the separate Prometheus connection tile: Grafana Cloud gives each of them their own instance ID.

2. Download pulseotlp_x.x.x.zip next to pulse_x.x.x.zip, from the same ModDB page or GitHub releases, and drop it into Mods/ as well.

   download pulseotlp_0.2.0.zip version 0.2.0, released 2026-09-29

3. Start the server once so the mod writes its own config file, then stop the server again.

4. Edit ModConfig/pulse-otlp.json. Three keys change:

   ModConfig/pulse-otlp.json

   {
     "Endpoint": "https://otlp-gateway-<region>.grafana.net/otlp",
     "Protocol": "http/protobuf",
     "Headers": {
       "Authorization": "<everything after Authorization= from step 1>"
     }
   }

   Leave every other key as the mod wrote it. Endpoint is the base address only, Pulse adds the rest of the path itself.

5. Start the server again. Look for a log line starting with Pulse OTLP exporting, which confirms it is pushing on a timer; by default that timer is 60 seconds, so give it a minute.

6. Confirm it arrived: in Grafana Cloud, open Explore, pick your Prometheus data source, and query pulse_players_online. A value coming back means it worked.

Once the numbers are flowing, bring in the dashboard:

1. In Grafana Cloud, go to Dashboards, then New, then Import dashboard.
2. You never cloned the repository for this path, so download the dashboard file directly: pulse-overview-shared.json (use that page's download button), then upload it in the Import dialog.

   download pulse-overview-shared.json same file as the GitHub link above

3. It asks for a Prometheus data source (Grafana's name for a saved connection to somewhere it can pull numbers from). Pick the one your Grafana Cloud stack already created for you: Grafana Cloud stores OTLP metrics in its own Prometheus-compatible store, so this is the same data source your other Grafana Cloud graphs use.
4. Open the imported dashboard. It is the same "Pulse server overview" dashboard as path A, and every panel on it reads the same way over this OTLP path too.

   

Every panel on this dashboard reads the same over OTLP as it does from a direct scrape. That used to not be true: nine panels (the two per-second network panels, the two attribution share panels, and five in the Runtime row) stayed empty over OTLP, because Grafana Cloud's own translation from OTLP into Prometheus-style names did not match what the dashboard queried, tracked in issue #77. 0.2 fixed both sides of that mismatch: three instruments had the wrong declared unit, and the runtime panels now query the same translated names Grafana Cloud already produced, so nothing here needs a workaround any more. See the main README's Runtime metrics section and the changelog if a dashboard or alert you built against the old names still needs updating.

the_oracle

What next

• Dashboard
  The dashboard covers every metric family the mod serves, grouped into rows.
• Attribution
  Tick busy time tells you the server is working hard. Attribution tells you what it is working on.
• Alerts deja_vu
  Eleven rules across tick health, engine warnings, log errors, endpoint availability, the worldgen queue and per-mod attribution.
• Install and configuration
  Pulse and the OTLP mod each keep their settings in their own file under ModConfig/, written with their defaults on first boot.