Releases · MathewRJ/RigSignal

11 Jun 12:17

v0.2.1

d153231

v0.2.1 Latest

Latest

RigSignal ships a real-time gaming performance telemetry agent that captures CPU, GPU, memory, storage, network, audio, power, and frame-timing metrics while you play and streams them to Elasticsearch for live dashboards and historical analysis.

What's in this release

Linux packages (.deb, .rpm, .pkg.tar.zst):

rigsignal-agent — the telemetry agent binary
rigsignal — unified launcher CLI (setup / start / stop / status / run %command%)
systemd user unit (rigsignal-agent.service)
Example config at /etc/rigsignal/rigsignal.toml
Three starter game profiles (Starfield, Cyberpunk 2077, Baldur's Gate 3)

Windows package (.msi):

rigsignal-agent.exe installed to C:\Program Files\RigSignal\bin\ (added to system PATH)
Example config at C:\Program Files\RigSignal\config\rigsignal.toml.example
Three starter game profiles at C:\Program Files\RigSignal\profiles\

eBPF probes (deep kernel-level GPU/CPU scheduler, block I/O, futex, VFS metrics) are not included in these packages — they require a nightly Rust toolchain and bpf-linker, and are Linux-only. Arch/CachyOS users who want eBPF should install from AUR (yay -S rigsignal-git) which builds everything from source. Windows is an eBPF-equivalent-free build by design.

Requirements

Linux x86_64, glibc 2.39+ (Ubuntu 24.04, Fedora 40, Arch, CachyOS, SteamOS 3.6+) — full feature set
Windows 10 / 11 x86_64 — agent only, no eBPF; some metrics partial (see "Windows caveats" below)
An Elasticsearch endpoint — the free tier on Elastic Cloud Serverless works
An API key with write access to metrics-rigsignal.* data streams (see Quick Start)
MangoHud (Linux) / PresentMon (Windows) — optional, required for frame timing (rigsignal.fps.* fields)

Installation

Arch Linux / CachyOS / Manjaro

Install the pre-built package from this release:

sudo pacman -U rigsignal-0.1.0-1-x86_64.pkg.tar.zst

Or install from AUR (includes eBPF probes, builds from source):

yay -S rigsignal-git

Debian / Ubuntu (24.04+)

sudo dpkg -i rigsignal-agent_0.1.0-1_amd64.deb

Fedora / RHEL / openSUSE

sudo rpm -i rigsignal-agent-0.1.0-1.x86_64.rpm

Windows 10 / 11

Double-click the .msi and accept the UAC prompt, or install silently from an admin PowerShell:

msiexec /i rigsignal-agent-0.1.0-x86_64.msi /qb!

The installer adds C:\Program Files\RigSignal\bin\ to the system PATH. Open a new terminal so rigsignal-agent is on PATH:

rigsignal-agent --version

To uninstall:

msiexec /x rigsignal-agent-0.1.0-x86_64.msi /qb!

or use Settings → Apps → Installed apps → RigSignal → Uninstall.

Windows caveats

No rigsignal launcher CLI — Windows has no systemd analog. Configure the agent by hand and run rigsignal-agent directly (or wrap it in a Steam launch option, see Quick Start §5).
gpu.temperature_c is reported via WMI ACPI thermal zones (best-effort, may be absent on some boards).
cpu.game_utilisation_pct, storage.game_io, audio.xruns, power.battery_rate_w are not populated on Windows in this release — the Linux equivalents require eBPF / hwmon / pw-top, which have no direct Windows counterpart yet.
Frame timing requires PresentMon. Place PresentMon.exe on PATH or set RIGSIGNAL_PRESENTMON=C:\path\to\PresentMon.exe. Without it, all other 7 collectors continue normally and rigsignal.fps.* fields are empty.

Quick Start

1. Get an Elasticsearch endpoint

Sign up for a free Elastic Cloud Serverless project. Copy the Elasticsearch endpoint URL from the project overview — it looks like https://your-project.es.us-central1.gcp.elastic.cloud.

2. Create an API key

In Kibana → Stack Management → API Keys, create a key with these privileges:

Index privileges: create_index, create, write, view_index_metadata on metrics-rigsignal.*
Cluster privileges: monitor

3. Run first-time setup

Linux:

rigsignal setup

Writes endpoint + API key to ~/.config/rigsignal/rigsignal.toml and verifies connectivity.

Windows (no rigsignal setup yet — manual config):

$cfgDir = "$env:APPDATA\RigSignal"
New-Item -ItemType Directory -Force -Path $cfgDir | Out-Null
Copy-Item "C:\Program Files\RigSignal\config\rigsignal.toml.example" "$cfgDir\rigsignal.toml"
notepad "$cfgDir\rigsignal.toml"   # fill in endpoint + api_key, save

Or skip the file and use environment variables (Windows + Linux both honour these):

[Environment]::SetEnvironmentVariable('ES_URL',     'https://your-project.es.us-central1.gcp.elastic.cloud', 'User')
[Environment]::SetEnvironmentVariable('ES_API_KEY', 'your-api-key-here',                                      'User')

4. Test with a dry run

rigsignal-agent --dry-run

You should see your hardware snapshot (CPU model, GPU, RAM) printed and collectors ready in the log. No data is written to Elasticsearch in dry-run mode.

5. Steam integration (Linux, recommended)

In Steam, right-click a game → Properties → Launch Options:

rigsignal run %command%

The agent starts automatically when the game launches and stops cleanly when you quit. Session data appears in Elasticsearch within a few seconds.

Windows: the launcher script is Linux-only in this release. Run rigsignal-agent.exe from any terminal before launching the game; it auto-detects Steam, Lutris, Heroic, Bottles, or use --target-name <ProcessName> / --target-pid <PID> to pin a specific process.

6. Manual start / stop

Linux (systemd-managed):

rigsignal start    # start the agent in the background via systemd
rigsignal status   # show current session label and service state
rigsignal stop     # stop the agent gracefully

Windows (no service yet — run the binary directly):

# Foreground (Ctrl+C to stop):
rigsignal-agent

# Background (PowerShell job):
$j = Start-Job { rigsignal-agent }
# ... play ...
Stop-Job $j; Remove-Job $j

Configuration

The agent searches for config in this order (first found wins):

Linux:

$RIGSIGNAL_CONFIG env var (full path)
~/.config/rigsignal/rigsignal.toml
/etc/rigsignal/rigsignal.toml

Windows:

%RIGSIGNAL_CONFIG% env var (full path)
%APPDATA%\RigSignal\rigsignal.toml (per-user — recommended)
%PROGRAMDATA%\RigSignal\rigsignal.toml (system-wide, all users)

The MSI installs a starting template at C:\Program Files\RigSignal\config\rigsignal.toml.example — copy it to one of the locations above and fill in your endpoint + API key.

Minimal config:

[elasticsearch]
endpoint = "https://your-project.es.us-central1.gcp.elastic.cloud"
api_key  = "your-api-key-here"

You can also pass credentials via environment variables (takes precedence over config):

export ES_URL="https://your-project.es.us-central1.gcp.elastic.cloud"
export ES_API_KEY="your-api-key-here"
rigsignal-agent

Full config reference: rigsignal-agent --help and the example at /etc/rigsignal/rigsignal.toml.

Game Profiles

RigSignal ships three starter profiles that auto-apply when the matching game is detected:

Game	Steam App ID	Auto-configured
Starfield	1716740	FSR 2, ray tracing, ultra preset
Cyberpunk 2077	1091500	DLSS / FSR 3 / XeSS, path tracing
Baldur's Gate 3	1086940	Vulkan

Profiles live at /usr/share/rigsignal/profiles/ (system) or ~/.config/rigsignal/profiles/ (user, takes precedence). Copy and edit one to create your own.

Troubleshooting

"No Elasticsearch endpoint configured"
Run rigsignal setup or set ES_URL and ES_API_KEY environment variables.

"ES ping failed" at startup
Check that your API key is valid and the endpoint URL ends in .es. (not .kb.). Run rigsignal-agent diagnose for a full connectivity report.

No frame timing data (rigsignal.fps.* fields are null)
MangoHud must be installed and on $PATH. On Arch: sudo pacman -S mangohud. On Ubuntu: sudo apt install mangohud. The agent will log a one-time warning if MangoHud is not found.

Agent doesn't detect my game
The agent detects Steam games automatically. For non-Steam games (Lutris, Heroic, Bottles) detection is also automatic. For anything else, pin the target manually:

rigsignal-agent --target-name "MyGame"
# or
rigsignal-agent --target-pid 12345

Permissions error on /proc
The agent reads /proc/<pid>/maps and /proc/<pid>/environ for settings auto-detection. This works without elevated privileges on standard desktop kernels. If you have a hardened kernel with restricted /proc access, run rigsignal-agent --log-level debug to see which reads are failing.

Session label counter is stuck at 1
The counter is stored in $XDG_STATE_HOME/rigsignal/session-counters.json (default ~/.local/state/rigsignal/). If the file is read-only or on a read-only filesystem, the agent falls back gracefully but can't increment. Check file permissions.

systemd unit fails to start
If you installed a dev build to /usr/local/bin/ instead of /usr/bin/, the unit's ExecStart path won't match. Create a drop-in override:

mkdir -p ~/.config/systemd/user/rigsignal-agent.service.d
cat > ~/.config/systemd/user/rigsignal-agent.service.d/override.conf <<EOF
[Service]
ExecStart=
ExecStart=/usr/local/bin/rigsignal-agent
EOF
systemctl --user daemon-reload

FAQ

Does RigSignal work with non-Steam games?
Yes. Lutris, Heroic (Epic/GOG), and Bottles are auto-detected. Any other game can be targeted by process name (--target-name) or PID (--target-pid). Automatic game detection via behavioural classification (GPU activity + fullscreen signals) is planned for a future release.
...

Contributors

MathewRJ

Assets 9

10 Jun 19:37

github-actions

v0.2.0

17d514f

v0.2.0

What's in this release

Linux packages (.deb, .rpm, .pkg.tar.zst):

rigsignal-agent — the telemetry agent binary
rigsignal — unified launcher CLI (setup / start / stop / status / run %command%)
systemd user unit (rigsignal-agent.service)
Example config at /etc/rigsignal/rigsignal.toml
Three starter game profiles (Starfield, Cyberpunk 2077, Baldur's Gate 3)

Windows package (.msi):

rigsignal-agent.exe installed to C:\Program Files\RigSignal\bin\ (added to system PATH)
Example config at C:\Program Files\RigSignal\config\rigsignal.toml.example
Three starter game profiles at C:\Program Files\RigSignal\profiles\

eBPF probes (deep kernel-level GPU/CPU scheduler, block I/O, futex, VFS metrics) are not included in these packages — they require a nightly Rust toolchain and bpf-linker, and are Linux-only. Arch/CachyOS users who want eBPF should install from AUR (yay -S rigsignal-git) which builds everything from source. Windows is an eBPF-equivalent-free build by design.

Requirements

Linux x86_64, glibc 2.39+ (Ubuntu 24.04, Fedora 40, Arch, CachyOS, SteamOS 3.6+) — full feature set
Windows 10 / 11 x86_64 — agent only, no eBPF; some metrics partial (see "Windows caveats" below)
An Elasticsearch endpoint — the free tier on Elastic Cloud Serverless works
An API key with write access to metrics-rigsignal.* data streams (see Quick Start)
MangoHud (Linux) / PresentMon (Windows) — optional, required for frame timing (rigsignal.fps.* fields)

Installation

Arch Linux / CachyOS / Manjaro

Install the pre-built package from this release:

sudo pacman -U rigsignal-0.1.0-1-x86_64.pkg.tar.zst

Or install from AUR (includes eBPF probes, builds from source):

yay -S rigsignal-git

Debian / Ubuntu (24.04+)

sudo dpkg -i rigsignal-agent_0.1.0-1_amd64.deb

Fedora / RHEL / openSUSE

sudo rpm -i rigsignal-agent-0.1.0-1.x86_64.rpm

Windows 10 / 11

Double-click the .msi and accept the UAC prompt, or install silently from an admin PowerShell:

msiexec /i rigsignal-agent-0.1.0-x86_64.msi /qb!

The installer adds C:\Program Files\RigSignal\bin\ to the system PATH. Open a new terminal so rigsignal-agent is on PATH:

rigsignal-agent --version

To uninstall:

msiexec /x rigsignal-agent-0.1.0-x86_64.msi /qb!

or use Settings → Apps → Installed apps → RigSignal → Uninstall.

Windows caveats

No rigsignal launcher CLI — Windows has no systemd analog. Configure the agent by hand and run rigsignal-agent directly (or wrap it in a Steam launch option, see Quick Start §5).
gpu.temperature_c is reported via WMI ACPI thermal zones (best-effort, may be absent on some boards).
cpu.game_utilisation_pct, storage.game_io, audio.xruns, power.battery_rate_w are not populated on Windows in this release — the Linux equivalents require eBPF / hwmon / pw-top, which have no direct Windows counterpart yet.
Frame timing requires PresentMon. Place PresentMon.exe on PATH or set RIGSIGNAL_PRESENTMON=C:\path\to\PresentMon.exe. Without it, all other 7 collectors continue normally and rigsignal.fps.* fields are empty.

Quick Start

1. Get an Elasticsearch endpoint

Sign up for a free Elastic Cloud Serverless project. Copy the Elasticsearch endpoint URL from the project overview — it looks like https://your-project.es.us-central1.gcp.elastic.cloud.

2. Create an API key

In Kibana → Stack Management → API Keys, create a key with these privileges:

Index privileges: create_index, create, write, view_index_metadata on metrics-rigsignal.*
Cluster privileges: monitor

3. Run first-time setup

Linux:

rigsignal setup

Writes endpoint + API key to ~/.config/rigsignal/rigsignal.toml and verifies connectivity.

Windows (no rigsignal setup yet — manual config):

$cfgDir = "$env:APPDATA\RigSignal"
New-Item -ItemType Directory -Force -Path $cfgDir | Out-Null
Copy-Item "C:\Program Files\RigSignal\config\rigsignal.toml.example" "$cfgDir\rigsignal.toml"
notepad "$cfgDir\rigsignal.toml"   # fill in endpoint + api_key, save

Or skip the file and use environment variables (Windows + Linux both honour these):

[Environment]::SetEnvironmentVariable('ES_URL',     'https://your-project.es.us-central1.gcp.elastic.cloud', 'User')
[Environment]::SetEnvironmentVariable('ES_API_KEY', 'your-api-key-here',                                      'User')

4. Test with a dry run

rigsignal-agent --dry-run

You should see your hardware snapshot (CPU model, GPU, RAM) printed and collectors ready in the log. No data is written to Elasticsearch in dry-run mode.

5. Steam integration (Linux, recommended)

In Steam, right-click a game → Properties → Launch Options:

rigsignal run %command%

The agent starts automatically when the game launches and stops cleanly when you quit. Session data appears in Elasticsearch within a few seconds.

Windows: the launcher script is Linux-only in this release. Run rigsignal-agent.exe from any terminal before launching the game; it auto-detects Steam, Lutris, Heroic, Bottles, or use --target-name <ProcessName> / --target-pid <PID> to pin a specific process.

6. Manual start / stop

Linux (systemd-managed):

rigsignal start    # start the agent in the background via systemd
rigsignal status   # show current session label and service state
rigsignal stop     # stop the agent gracefully

Windows (no service yet — run the binary directly):

# Foreground (Ctrl+C to stop):
rigsignal-agent

# Background (PowerShell job):
$j = Start-Job { rigsignal-agent }
# ... play ...
Stop-Job $j; Remove-Job $j

Configuration

The agent searches for config in this order (first found wins):

Linux:

$RIGSIGNAL_CONFIG env var (full path)
~/.config/rigsignal/rigsignal.toml
/etc/rigsignal/rigsignal.toml

Windows:

%RIGSIGNAL_CONFIG% env var (full path)
%APPDATA%\RigSignal\rigsignal.toml (per-user — recommended)
%PROGRAMDATA%\RigSignal\rigsignal.toml (system-wide, all users)

The MSI installs a starting template at C:\Program Files\RigSignal\config\rigsignal.toml.example — copy it to one of the locations above and fill in your endpoint + API key.

Minimal config:

[elasticsearch]
endpoint = "https://your-project.es.us-central1.gcp.elastic.cloud"
api_key  = "your-api-key-here"

You can also pass credentials via environment variables (takes precedence over config):

export ES_URL="https://your-project.es.us-central1.gcp.elastic.cloud"
export ES_API_KEY="your-api-key-here"
rigsignal-agent

Full config reference: rigsignal-agent --help and the example at /etc/rigsignal/rigsignal.toml.

Game Profiles

RigSignal ships three starter profiles that auto-apply when the matching game is detected:

Game	Steam App ID	Auto-configured
Starfield	1716740	FSR 2, ray tracing, ultra preset
Cyberpunk 2077	1091500	DLSS / FSR 3 / XeSS, path tracing
Baldur's Gate 3	1086940	Vulkan

Profiles live at /usr/share/rigsignal/profiles/ (system) or ~/.config/rigsignal/profiles/ (user, takes precedence). Copy and edit one to create your own.

Troubleshooting

"No Elasticsearch endpoint configured"
Run rigsignal setup or set ES_URL and ES_API_KEY environment variables.

"ES ping failed" at startup
Check that your API key is valid and the endpoint URL ends in .es. (not .kb.). Run rigsignal-agent diagnose for a full connectivity report.

Agent doesn't detect my game
The agent detects Steam games automatically. For non-Steam games (Lutris, Heroic, Bottles) detection is also automatic. For anything else, pin the target manually:

rigsignal-agent --target-name "MyGame"
# or
rigsignal-agent --target-pid 12345

systemd unit fails to start
If you installed a dev build to /usr/local/bin/ instead of /usr/bin/, the unit's ExecStart path won't match. Create a drop-in override:

mkdir -p ~/.config/systemd/user/rigsignal-agent.service.d
cat > ~/.config/systemd/user/rigsignal-agent.service.d/override.conf <<EOF
[Service]
ExecStart=
ExecStart=/usr/local/bin/rigsignal-agent
EOF
systemctl --user daemon-reload

FAQ

Assets 9

09 May 12:16

github-actions

v0.1.7

8d45c6e

v0.1.7

GamePulse ships a real-time gaming performance telemetry agent that captures CPU, GPU, memory, storage, network, audio, power, and frame-timing metrics while you play and streams them to Elasticsearch for live dashboards and historical analysis.

What's in this release

Linux packages (.deb, .rpm, .pkg.tar.zst):

gamepulse-agent — the telemetry agent binary
gamepulse — unified launcher CLI (setup / start / stop / status / run %command%)
systemd user unit (gamepulse-agent.service)
Example config at /etc/gamepulse/gamepulse.toml
Three starter game profiles (Starfield, Cyberpunk 2077, Baldur's Gate 3)

Windows package (.msi):

gamepulse-agent.exe installed to C:\Program Files\GamePulse\bin\ (added to system PATH)
Example config at C:\Program Files\GamePulse\config\gamepulse.toml.example
Three starter game profiles at C:\Program Files\GamePulse\profiles\

eBPF probes (deep kernel-level GPU/CPU scheduler, block I/O, futex, VFS metrics) are not included in these packages — they require a nightly Rust toolchain and bpf-linker, and are Linux-only. Arch/CachyOS users who want eBPF should install from AUR (yay -S gamepulse-git) which builds everything from source. Windows is an eBPF-equivalent-free build by design.

Requirements

Linux x86_64, glibc 2.39+ (Ubuntu 24.04, Fedora 40, Arch, CachyOS, SteamOS 3.6+) — full feature set
Windows 10 / 11 x86_64 — agent only, no eBPF; some metrics partial (see "Windows caveats" below)
An Elasticsearch endpoint — the free tier on Elastic Cloud Serverless works
An API key with write access to metrics-gamepulse.* data streams (see Quick Start)
MangoHud (Linux) / PresentMon (Windows) — optional, required for frame timing (gamepulse.fps.* fields)

Installation

Arch Linux / CachyOS / Manjaro

Install the pre-built package from this release:

sudo pacman -U gamepulse-0.1.0-1-x86_64.pkg.tar.zst

Or install from AUR (includes eBPF probes, builds from source):

yay -S gamepulse-git

Debian / Ubuntu (24.04+)

sudo dpkg -i gamepulse-agent_0.1.0-1_amd64.deb

Fedora / RHEL / openSUSE

sudo rpm -i gamepulse-agent-0.1.0-1.x86_64.rpm

Windows 10 / 11

Double-click the .msi and accept the UAC prompt, or install silently from an admin PowerShell:

msiexec /i gamepulse-agent-0.1.0-x86_64.msi /qb!

The installer adds C:\Program Files\GamePulse\bin\ to the system PATH. Open a new terminal so gamepulse-agent is on PATH:

gamepulse-agent --version

To uninstall:

msiexec /x gamepulse-agent-0.1.0-x86_64.msi /qb!

or use Settings → Apps → Installed apps → GamePulse → Uninstall.

Windows caveats

No gamepulse launcher CLI — Windows has no systemd analog. Configure the agent by hand and run gamepulse-agent directly (or wrap it in a Steam launch option, see Quick Start §5).
gpu.temperature_c is reported via WMI ACPI thermal zones (best-effort, may be absent on some boards).
cpu.game_utilisation_pct, storage.game_io, audio.xruns, power.battery_rate_w are not populated on Windows in this release — the Linux equivalents require eBPF / hwmon / pw-top, which have no direct Windows counterpart yet.
Frame timing requires PresentMon. Place PresentMon.exe on PATH or set GAMEPULSE_PRESENTMON=C:\path\to\PresentMon.exe. Without it, all other 7 collectors continue normally and gamepulse.fps.* fields are empty.

Quick Start

1. Get an Elasticsearch endpoint

Sign up for a free Elastic Cloud Serverless project. Copy the Elasticsearch endpoint URL from the project overview — it looks like https://your-project.es.us-central1.gcp.elastic.cloud.

2. Create an API key

In Kibana → Stack Management → API Keys, create a key with these privileges:

Index privileges: create_index, create, write, view_index_metadata on metrics-gamepulse.*
Cluster privileges: monitor

3. Run first-time setup

Linux:

gamepulse setup

Writes endpoint + API key to ~/.config/gamepulse/gamepulse.toml and verifies connectivity.

Windows (no gamepulse setup yet — manual config):

$cfgDir = "$env:APPDATA\GamePulse"
New-Item -ItemType Directory -Force -Path $cfgDir | Out-Null
Copy-Item "C:\Program Files\GamePulse\config\gamepulse.toml.example" "$cfgDir\gamepulse.toml"
notepad "$cfgDir\gamepulse.toml"   # fill in endpoint + api_key, save

Or skip the file and use environment variables (Windows + Linux both honour these):

[Environment]::SetEnvironmentVariable('ES_URL',     'https://your-project.es.us-central1.gcp.elastic.cloud', 'User')
[Environment]::SetEnvironmentVariable('ES_API_KEY', 'your-api-key-here',                                      'User')

4. Test with a dry run

gamepulse-agent --dry-run

You should see your hardware snapshot (CPU model, GPU, RAM) printed and collectors ready in the log. No data is written to Elasticsearch in dry-run mode.

5. Steam integration (Linux, recommended)

In Steam, right-click a game → Properties → Launch Options:

gamepulse run %command%

The agent starts automatically when the game launches and stops cleanly when you quit. Session data appears in Elasticsearch within a few seconds.

Windows: the launcher script is Linux-only in this release. Run gamepulse-agent.exe from any terminal before launching the game; it auto-detects Steam, Lutris, Heroic, Bottles, or use --target-name <ProcessName> / --target-pid <PID> to pin a specific process.

6. Manual start / stop

Linux (systemd-managed):

gamepulse start    # start the agent in the background via systemd
gamepulse status   # show current session label and service state
gamepulse stop     # stop the agent gracefully

Windows (no service yet — run the binary directly):

# Foreground (Ctrl+C to stop):
gamepulse-agent

# Background (PowerShell job):
$j = Start-Job { gamepulse-agent }
# ... play ...
Stop-Job $j; Remove-Job $j

Configuration

The agent searches for config in this order (first found wins):

Linux:

$GAMEPULSE_CONFIG env var (full path)
~/.config/gamepulse/gamepulse.toml
/etc/gamepulse/gamepulse.toml

Windows:

%GAMEPULSE_CONFIG% env var (full path)
%APPDATA%\GamePulse\gamepulse.toml (per-user — recommended)
%PROGRAMDATA%\GamePulse\gamepulse.toml (system-wide, all users)

The MSI installs a starting template at C:\Program Files\GamePulse\config\gamepulse.toml.example — copy it to one of the locations above and fill in your endpoint + API key.

Minimal config:

[elasticsearch]
endpoint = "https://your-project.es.us-central1.gcp.elastic.cloud"
api_key  = "your-api-key-here"

You can also pass credentials via environment variables (takes precedence over config):

export ES_URL="https://your-project.es.us-central1.gcp.elastic.cloud"
export ES_API_KEY="your-api-key-here"
gamepulse-agent

Full config reference: gamepulse-agent --help and the example at /etc/gamepulse/gamepulse.toml.

Game Profiles

GamePulse ships three starter profiles that auto-apply when the matching game is detected:

Game	Steam App ID	Auto-configured
Starfield	1716740	FSR 2, ray tracing, ultra preset
Cyberpunk 2077	1091500	DLSS / FSR 3 / XeSS, path tracing
Baldur's Gate 3	1086940	Vulkan

Profiles live at /usr/share/gamepulse/profiles/ (system) or ~/.config/gamepulse/profiles/ (user, takes precedence). Copy and edit one to create your own.

Troubleshooting

"No Elasticsearch endpoint configured"
Run gamepulse setup or set ES_URL and ES_API_KEY environment variables.

"ES ping failed" at startup
Check that your API key is valid and the endpoint URL ends in .es. (not .kb.). Run gamepulse-agent diagnose for a full connectivity report.

No frame timing data (gamepulse.fps.* fields are null)
MangoHud must be installed and on $PATH. On Arch: sudo pacman -S mangohud. On Ubuntu: sudo apt install mangohud. The agent will log a one-time warning if MangoHud is not found.

Agent doesn't detect my game
The agent detects Steam games automatically. For non-Steam games (Lutris, Heroic, Bottles) detection is also automatic. For anything else, pin the target manually:

gamepulse-agent --target-name "MyGame"
# or
gamepulse-agent --target-pid 12345

Permissions error on /proc
The agent reads /proc/<pid>/maps and /proc/<pid>/environ for settings auto-detection. This works without elevated privileges on standard desktop kernels. If you have a hardened kernel with restricted /proc access, run gamepulse-agent --log-level debug to see which reads are failing.

Session label counter is stuck at 1
The counter is stored in $XDG_STATE_HOME/gamepulse/session-counters.json (default ~/.local/state/gamepulse/). If the file is read-only or on a read-only filesystem, the agent falls back gracefully but can't increment. Check file permissions.

systemd unit fails to start
If you installed a dev build to /usr/local/bin/ instead of /usr/bin/, the unit's ExecStart path won't match. Create a drop-in override:

mkdir -p ~/.config/systemd/user/gamepulse-agent.service.d
cat > ~/.config/systemd/user/gamepulse-agent.service.d/override.conf <<EOF
[Service]
ExecStart=
ExecStart=/usr/local/bin/gamepulse-agent
EOF
systemctl --user daemon-reload

FAQ

Does GamePulse work with non-Steam games?
Yes. Lutris, Heroic (Epic/GOG), and Bottles are auto-detected. Any other game can be targeted by process name (--target-name) or PID (--target-pid). Automatic game detection via behavioural classification (GPU activity + fullscreen signals) is planned for a future release.
...

Assets 9

08 May 20:19

github-actions

v0.1.6

fbec9e7

v0.1.6

What's in this release

Linux packages (.deb, .rpm, .pkg.tar.zst):

gamepulse-agent — the telemetry agent binary
gamepulse — unified launcher CLI (setup / start / stop / status / run %command%)
systemd user unit (gamepulse-agent.service)
Example config at /etc/gamepulse/gamepulse.toml
Three starter game profiles (Starfield, Cyberpunk 2077, Baldur's Gate 3)

Windows package (.msi):

gamepulse-agent.exe installed to C:\Program Files\GamePulse\bin\ (added to system PATH)
Example config at C:\Program Files\GamePulse\config\gamepulse.toml.example
Three starter game profiles at C:\Program Files\GamePulse\profiles\

eBPF probes (deep kernel-level GPU/CPU scheduler, block I/O, futex, VFS metrics) are not included in these packages — they require a nightly Rust toolchain and bpf-linker, and are Linux-only. Arch/CachyOS users who want eBPF should install from AUR (yay -S gamepulse-git) which builds everything from source. Windows is an eBPF-equivalent-free build by design.

Requirements

Linux x86_64, glibc 2.39+ (Ubuntu 24.04, Fedora 40, Arch, CachyOS, SteamOS 3.6+) — full feature set
Windows 10 / 11 x86_64 — agent only, no eBPF; some metrics partial (see "Windows caveats" below)
An Elasticsearch endpoint — the free tier on Elastic Cloud Serverless works
An API key with write access to metrics-gamepulse.* data streams (see Quick Start)
MangoHud (Linux) / PresentMon (Windows) — optional, required for frame timing (gamepulse.fps.* fields)

Installation

Arch Linux / CachyOS / Manjaro

Install the pre-built package from this release:

sudo pacman -U gamepulse-0.1.0-1-x86_64.pkg.tar.zst

Or install from AUR (includes eBPF probes, builds from source):

yay -S gamepulse-git

Debian / Ubuntu (24.04+)

sudo dpkg -i gamepulse-agent_0.1.0-1_amd64.deb

Fedora / RHEL / openSUSE

sudo rpm -i gamepulse-agent-0.1.0-1.x86_64.rpm

Windows 10 / 11

Double-click the .msi and accept the UAC prompt, or install silently from an admin PowerShell:

msiexec /i gamepulse-agent-0.1.0-x86_64.msi /qb!

The installer adds C:\Program Files\GamePulse\bin\ to the system PATH. Open a new terminal so gamepulse-agent is on PATH:

gamepulse-agent --version

To uninstall:

msiexec /x gamepulse-agent-0.1.0-x86_64.msi /qb!

or use Settings → Apps → Installed apps → GamePulse → Uninstall.

Windows caveats

No gamepulse launcher CLI — Windows has no systemd analog. Configure the agent by hand and run gamepulse-agent directly (or wrap it in a Steam launch option, see Quick Start §5).
gpu.temperature_c is reported via WMI ACPI thermal zones (best-effort, may be absent on some boards).
cpu.game_utilisation_pct, storage.game_io, audio.xruns, power.battery_rate_w are not populated on Windows in this release — the Linux equivalents require eBPF / hwmon / pw-top, which have no direct Windows counterpart yet.
Frame timing requires PresentMon. Place PresentMon.exe on PATH or set GAMEPULSE_PRESENTMON=C:\path\to\PresentMon.exe. Without it, all other 7 collectors continue normally and gamepulse.fps.* fields are empty.

Quick Start

1. Get an Elasticsearch endpoint

Sign up for a free Elastic Cloud Serverless project. Copy the Elasticsearch endpoint URL from the project overview — it looks like https://your-project.es.us-central1.gcp.elastic.cloud.

2. Create an API key

In Kibana → Stack Management → API Keys, create a key with these privileges:

Index privileges: create_index, create, write, view_index_metadata on metrics-gamepulse.*
Cluster privileges: monitor

3. Run first-time setup

Linux:

gamepulse setup

Writes endpoint + API key to ~/.config/gamepulse/gamepulse.toml and verifies connectivity.

Windows (no gamepulse setup yet — manual config):

$cfgDir = "$env:APPDATA\GamePulse"
New-Item -ItemType Directory -Force -Path $cfgDir | Out-Null
Copy-Item "C:\Program Files\GamePulse\config\gamepulse.toml.example" "$cfgDir\gamepulse.toml"
notepad "$cfgDir\gamepulse.toml"   # fill in endpoint + api_key, save

Or skip the file and use environment variables (Windows + Linux both honour these):

[Environment]::SetEnvironmentVariable('ES_URL',     'https://your-project.es.us-central1.gcp.elastic.cloud', 'User')
[Environment]::SetEnvironmentVariable('ES_API_KEY', 'your-api-key-here',                                      'User')

4. Test with a dry run

gamepulse-agent --dry-run

You should see your hardware snapshot (CPU model, GPU, RAM) printed and collectors ready in the log. No data is written to Elasticsearch in dry-run mode.

5. Steam integration (Linux, recommended)

In Steam, right-click a game → Properties → Launch Options:

gamepulse run %command%

The agent starts automatically when the game launches and stops cleanly when you quit. Session data appears in Elasticsearch within a few seconds.

Windows: the launcher script is Linux-only in this release. Run gamepulse-agent.exe from any terminal before launching the game; it auto-detects Steam, Lutris, Heroic, Bottles, or use --target-name <ProcessName> / --target-pid <PID> to pin a specific process.

6. Manual start / stop

Linux (systemd-managed):

gamepulse start    # start the agent in the background via systemd
gamepulse status   # show current session label and service state
gamepulse stop     # stop the agent gracefully

Windows (no service yet — run the binary directly):

# Foreground (Ctrl+C to stop):
gamepulse-agent

# Background (PowerShell job):
$j = Start-Job { gamepulse-agent }
# ... play ...
Stop-Job $j; Remove-Job $j

Configuration

The agent searches for config in this order (first found wins):

Linux:

$GAMEPULSE_CONFIG env var (full path)
~/.config/gamepulse/gamepulse.toml
/etc/gamepulse/gamepulse.toml

Windows:

%GAMEPULSE_CONFIG% env var (full path)
%APPDATA%\GamePulse\gamepulse.toml (per-user — recommended)
%PROGRAMDATA%\GamePulse\gamepulse.toml (system-wide, all users)

The MSI installs a starting template at C:\Program Files\GamePulse\config\gamepulse.toml.example — copy it to one of the locations above and fill in your endpoint + API key.

Minimal config:

[elasticsearch]
endpoint = "https://your-project.es.us-central1.gcp.elastic.cloud"
api_key  = "your-api-key-here"

You can also pass credentials via environment variables (takes precedence over config):

export ES_URL="https://your-project.es.us-central1.gcp.elastic.cloud"
export ES_API_KEY="your-api-key-here"
gamepulse-agent

Full config reference: gamepulse-agent --help and the example at /etc/gamepulse/gamepulse.toml.

Game Profiles

GamePulse ships three starter profiles that auto-apply when the matching game is detected:

Game	Steam App ID	Auto-configured
Starfield	1716740	FSR 2, ray tracing, ultra preset
Cyberpunk 2077	1091500	DLSS / FSR 3 / XeSS, path tracing
Baldur's Gate 3	1086940	Vulkan

Profiles live at /usr/share/gamepulse/profiles/ (system) or ~/.config/gamepulse/profiles/ (user, takes precedence). Copy and edit one to create your own.

Troubleshooting

"No Elasticsearch endpoint configured"
Run gamepulse setup or set ES_URL and ES_API_KEY environment variables.

"ES ping failed" at startup
Check that your API key is valid and the endpoint URL ends in .es. (not .kb.). Run gamepulse-agent diagnose for a full connectivity report.

Agent doesn't detect my game
The agent detects Steam games automatically. For non-Steam games (Lutris, Heroic, Bottles) detection is also automatic. For anything else, pin the target manually:

gamepulse-agent --target-name "MyGame"
# or
gamepulse-agent --target-pid 12345

Permissions error on /proc
The agent reads /proc/<pid>/maps and /proc/<pid>/environ for settings auto-detection. This works without elevated privileges on standard desktop kernels. If you have a hardened kernel with restricted /proc access, run gamepulse-agent --log-level debug to see which reads are failing.

systemd unit fails to start
If you installed a dev build to /usr/local/bin/ instead of /usr/bin/, the unit's ExecStart path won't match. Create a drop-in override:

mkdir -p ~/.config/systemd/user/gamepulse-agent.service.d
cat > ~/.config/systemd/user/gamepulse-agent.service.d/override.conf <<EOF
[Service]
ExecStart=
ExecStart=/usr/local/bin/gamepulse-agent
EOF
systemctl --user daemon-reload

FAQ

Assets 9

08 May 19:27

github-actions

v0.1.5

f02984e

v0.1.5

What's in this release

Linux packages (.deb, .rpm, .pkg.tar.zst):

gamepulse-agent — the telemetry agent binary
gamepulse — unified launcher CLI (setup / start / stop / status / run %command%)
systemd user unit (gamepulse-agent.service)
Example config at /etc/gamepulse/gamepulse.toml
Three starter game profiles (Starfield, Cyberpunk 2077, Baldur's Gate 3)

Windows package (.msi):

gamepulse-agent.exe installed to C:\Program Files\GamePulse\bin\ (added to system PATH)
Example config at C:\Program Files\GamePulse\config\gamepulse.toml.example
Three starter game profiles at C:\Program Files\GamePulse\profiles\

eBPF probes (deep kernel-level GPU/CPU scheduler, block I/O, futex, VFS metrics) are not included in these packages — they require a nightly Rust toolchain and bpf-linker, and are Linux-only. Arch/CachyOS users who want eBPF should install from AUR (yay -S gamepulse-git) which builds everything from source. Windows is an eBPF-equivalent-free build by design.

Requirements

Linux x86_64, glibc 2.39+ (Ubuntu 24.04, Fedora 40, Arch, CachyOS, SteamOS 3.6+) — full feature set
Windows 10 / 11 x86_64 — agent only, no eBPF; some metrics partial (see "Windows caveats" below)
An Elasticsearch endpoint — the free tier on Elastic Cloud Serverless works
An API key with write access to metrics-gamepulse.* data streams (see Quick Start)
MangoHud (Linux) / PresentMon (Windows) — optional, required for frame timing (gamepulse.fps.* fields)

Installation

Arch Linux / CachyOS / Manjaro

Install the pre-built package from this release:

sudo pacman -U gamepulse-0.1.0-1-x86_64.pkg.tar.zst

Or install from AUR (includes eBPF probes, builds from source):

yay -S gamepulse-git

Debian / Ubuntu (24.04+)

sudo dpkg -i gamepulse-agent_0.1.0-1_amd64.deb

Fedora / RHEL / openSUSE

sudo rpm -i gamepulse-agent-0.1.0-1.x86_64.rpm

Windows 10 / 11

Double-click the .msi and accept the UAC prompt, or install silently from an admin PowerShell:

msiexec /i gamepulse-agent-0.1.0-x86_64.msi /qb!

The installer adds C:\Program Files\GamePulse\bin\ to the system PATH. Open a new terminal so gamepulse-agent is on PATH:

gamepulse-agent --version

To uninstall:

msiexec /x gamepulse-agent-0.1.0-x86_64.msi /qb!

or use Settings → Apps → Installed apps → GamePulse → Uninstall.

Windows caveats

No gamepulse launcher CLI — Windows has no systemd analog. Configure the agent by hand and run gamepulse-agent directly (or wrap it in a Steam launch option, see Quick Start §5).
gpu.temperature_c is reported via WMI ACPI thermal zones (best-effort, may be absent on some boards).
cpu.game_utilisation_pct, storage.game_io, audio.xruns, power.battery_rate_w are not populated on Windows in this release — the Linux equivalents require eBPF / hwmon / pw-top, which have no direct Windows counterpart yet.
Frame timing requires PresentMon. Place PresentMon.exe on PATH or set GAMEPULSE_PRESENTMON=C:\path\to\PresentMon.exe. Without it, all other 7 collectors continue normally and gamepulse.fps.* fields are empty.

Quick Start

1. Get an Elasticsearch endpoint

Sign up for a free Elastic Cloud Serverless project. Copy the Elasticsearch endpoint URL from the project overview — it looks like https://your-project.es.us-central1.gcp.elastic.cloud.

2. Create an API key

In Kibana → Stack Management → API Keys, create a key with these privileges:

Index privileges: create_index, create, write, view_index_metadata on metrics-gamepulse.*
Cluster privileges: monitor

3. Run first-time setup

Linux:

gamepulse setup

Writes endpoint + API key to ~/.config/gamepulse/gamepulse.toml and verifies connectivity.

Windows (no gamepulse setup yet — manual config):

$cfgDir = "$env:APPDATA\GamePulse"
New-Item -ItemType Directory -Force -Path $cfgDir | Out-Null
Copy-Item "C:\Program Files\GamePulse\config\gamepulse.toml.example" "$cfgDir\gamepulse.toml"
notepad "$cfgDir\gamepulse.toml"   # fill in endpoint + api_key, save

Or skip the file and use environment variables (Windows + Linux both honour these):

[Environment]::SetEnvironmentVariable('ES_URL',     'https://your-project.es.us-central1.gcp.elastic.cloud', 'User')
[Environment]::SetEnvironmentVariable('ES_API_KEY', 'your-api-key-here',                                      'User')

4. Test with a dry run

gamepulse-agent --dry-run

You should see your hardware snapshot (CPU model, GPU, RAM) printed and collectors ready in the log. No data is written to Elasticsearch in dry-run mode.

5. Steam integration (Linux, recommended)

In Steam, right-click a game → Properties → Launch Options:

gamepulse run %command%

The agent starts automatically when the game launches and stops cleanly when you quit. Session data appears in Elasticsearch within a few seconds.

Windows: the launcher script is Linux-only in this release. Run gamepulse-agent.exe from any terminal before launching the game; it auto-detects Steam, Lutris, Heroic, Bottles, or use --target-name <ProcessName> / --target-pid <PID> to pin a specific process.

6. Manual start / stop

Linux (systemd-managed):

gamepulse start    # start the agent in the background via systemd
gamepulse status   # show current session label and service state
gamepulse stop     # stop the agent gracefully

Windows (no service yet — run the binary directly):

# Foreground (Ctrl+C to stop):
gamepulse-agent

# Background (PowerShell job):
$j = Start-Job { gamepulse-agent }
# ... play ...
Stop-Job $j; Remove-Job $j

Configuration

The agent searches for config in this order (first found wins):

Linux:

$GAMEPULSE_CONFIG env var (full path)
~/.config/gamepulse/gamepulse.toml
/etc/gamepulse/gamepulse.toml

Windows:

%GAMEPULSE_CONFIG% env var (full path)
%APPDATA%\GamePulse\gamepulse.toml (per-user — recommended)
%PROGRAMDATA%\GamePulse\gamepulse.toml (system-wide, all users)

The MSI installs a starting template at C:\Program Files\GamePulse\config\gamepulse.toml.example — copy it to one of the locations above and fill in your endpoint + API key.

Minimal config:

[elasticsearch]
endpoint = "https://your-project.es.us-central1.gcp.elastic.cloud"
api_key  = "your-api-key-here"

You can also pass credentials via environment variables (takes precedence over config):

export ES_URL="https://your-project.es.us-central1.gcp.elastic.cloud"
export ES_API_KEY="your-api-key-here"
gamepulse-agent

Full config reference: gamepulse-agent --help and the example at /etc/gamepulse/gamepulse.toml.

Game Profiles

GamePulse ships three starter profiles that auto-apply when the matching game is detected:

Game	Steam App ID	Auto-configured
Starfield	1716740	FSR 2, ray tracing, ultra preset
Cyberpunk 2077	1091500	DLSS / FSR 3 / XeSS, path tracing
Baldur's Gate 3	1086940	Vulkan

Profiles live at /usr/share/gamepulse/profiles/ (system) or ~/.config/gamepulse/profiles/ (user, takes precedence). Copy and edit one to create your own.

Troubleshooting

"No Elasticsearch endpoint configured"
Run gamepulse setup or set ES_URL and ES_API_KEY environment variables.

"ES ping failed" at startup
Check that your API key is valid and the endpoint URL ends in .es. (not .kb.). Run gamepulse-agent diagnose for a full connectivity report.

Agent doesn't detect my game
The agent detects Steam games automatically. For non-Steam games (Lutris, Heroic, Bottles) detection is also automatic. For anything else, pin the target manually:

gamepulse-agent --target-name "MyGame"
# or
gamepulse-agent --target-pid 12345

Permissions error on /proc
The agent reads /proc/<pid>/maps and /proc/<pid>/environ for settings auto-detection. This works without elevated privileges on standard desktop kernels. If you have a hardened kernel with restricted /proc access, run gamepulse-agent --log-level debug to see which reads are failing.

systemd unit fails to start
If you installed a dev build to /usr/local/bin/ instead of /usr/bin/, the unit's ExecStart path won't match. Create a drop-in override:

mkdir -p ~/.config/systemd/user/gamepulse-agent.service.d
cat > ~/.config/systemd/user/gamepulse-agent.service.d/override.conf <<EOF
[Service]
ExecStart=
ExecStart=/usr/local/bin/gamepulse-agent
EOF
systemctl --user daemon-reload

FAQ

Assets 9

08 May 17:37

github-actions

v0.1.4

63c31dc

v0.1.4

What's in this release

Linux packages (.deb, .rpm, .pkg.tar.zst):

gamepulse-agent — the telemetry agent binary
gamepulse — unified launcher CLI (setup / start / stop / status / run %command%)
systemd user unit (gamepulse-agent.service)
Example config at /etc/gamepulse/gamepulse.toml
Three starter game profiles (Starfield, Cyberpunk 2077, Baldur's Gate 3)

Windows package (.msi):

gamepulse-agent.exe installed to C:\Program Files\GamePulse\bin\ (added to system PATH)
Example config at C:\Program Files\GamePulse\config\gamepulse.toml.example
Three starter game profiles at C:\Program Files\GamePulse\profiles\

eBPF probes (deep kernel-level GPU/CPU scheduler, block I/O, futex, VFS metrics) are not included in these packages — they require a nightly Rust toolchain and bpf-linker, and are Linux-only. Arch/CachyOS users who want eBPF should install from AUR (yay -S gamepulse-git) which builds everything from source. Windows is an eBPF-equivalent-free build by design.

Requirements

Linux x86_64, glibc 2.39+ (Ubuntu 24.04, Fedora 40, Arch, CachyOS, SteamOS 3.6+) — full feature set
Windows 10 / 11 x86_64 — agent only, no eBPF; some metrics partial (see "Windows caveats" below)
An Elasticsearch endpoint — the free tier on Elastic Cloud Serverless works
An API key with write access to metrics-gamepulse.* data streams (see Quick Start)
MangoHud (Linux) / PresentMon (Windows) — optional, required for frame timing (gamepulse.fps.* fields)

Installation

Arch Linux / CachyOS / Manjaro

Install the pre-built package from this release:

sudo pacman -U gamepulse-0.1.0-1-x86_64.pkg.tar.zst

Or install from AUR (includes eBPF probes, builds from source):

yay -S gamepulse-git

Debian / Ubuntu (24.04+)

sudo dpkg -i gamepulse-agent_0.1.0-1_amd64.deb

Fedora / RHEL / openSUSE

sudo rpm -i gamepulse-agent-0.1.0-1.x86_64.rpm

Windows 10 / 11

Double-click the .msi and accept the UAC prompt, or install silently from an admin PowerShell:

msiexec /i gamepulse-agent-0.1.0-x86_64.msi /qb!

The installer adds C:\Program Files\GamePulse\bin\ to the system PATH. Open a new terminal so gamepulse-agent is on PATH:

gamepulse-agent --version

To uninstall:

msiexec /x gamepulse-agent-0.1.0-x86_64.msi /qb!

or use Settings → Apps → Installed apps → GamePulse → Uninstall.

Windows caveats

No gamepulse launcher CLI — Windows has no systemd analog. Configure the agent by hand and run gamepulse-agent directly (or wrap it in a Steam launch option, see Quick Start §5).
gpu.temperature_c is reported via WMI ACPI thermal zones (best-effort, may be absent on some boards).
cpu.game_utilisation_pct, storage.game_io, audio.xruns, power.battery_rate_w are not populated on Windows in this release — the Linux equivalents require eBPF / hwmon / pw-top, which have no direct Windows counterpart yet.
Frame timing requires PresentMon. Place PresentMon.exe on PATH or set GAMEPULSE_PRESENTMON=C:\path\to\PresentMon.exe. Without it, all other 7 collectors continue normally and gamepulse.fps.* fields are empty.

Quick Start

1. Get an Elasticsearch endpoint

Sign up for a free Elastic Cloud Serverless project. Copy the Elasticsearch endpoint URL from the project overview — it looks like https://your-project.es.us-central1.gcp.elastic.cloud.

2. Create an API key

In Kibana → Stack Management → API Keys, create a key with these privileges:

Index privileges: create_index, create, write, view_index_metadata on metrics-gamepulse.*
Cluster privileges: monitor

3. Run first-time setup

Linux:

gamepulse setup

Writes endpoint + API key to ~/.config/gamepulse/gamepulse.toml and verifies connectivity.

Windows (no gamepulse setup yet — manual config):

$cfgDir = "$env:APPDATA\GamePulse"
New-Item -ItemType Directory -Force -Path $cfgDir | Out-Null
Copy-Item "C:\Program Files\GamePulse\config\gamepulse.toml.example" "$cfgDir\gamepulse.toml"
notepad "$cfgDir\gamepulse.toml"   # fill in endpoint + api_key, save

Or skip the file and use environment variables (Windows + Linux both honour these):

[Environment]::SetEnvironmentVariable('ES_URL',     'https://your-project.es.us-central1.gcp.elastic.cloud', 'User')
[Environment]::SetEnvironmentVariable('ES_API_KEY', 'your-api-key-here',                                      'User')

4. Test with a dry run

gamepulse-agent --dry-run

You should see your hardware snapshot (CPU model, GPU, RAM) printed and collectors ready in the log. No data is written to Elasticsearch in dry-run mode.

5. Steam integration (Linux, recommended)

In Steam, right-click a game → Properties → Launch Options:

gamepulse run %command%

The agent starts automatically when the game launches and stops cleanly when you quit. Session data appears in Elasticsearch within a few seconds.

Windows: the launcher script is Linux-only in this release. Run gamepulse-agent.exe from any terminal before launching the game; it auto-detects Steam, Lutris, Heroic, Bottles, or use --target-name <ProcessName> / --target-pid <PID> to pin a specific process.

6. Manual start / stop

Linux (systemd-managed):

gamepulse start    # start the agent in the background via systemd
gamepulse status   # show current session label and service state
gamepulse stop     # stop the agent gracefully

Windows (no service yet — run the binary directly):

# Foreground (Ctrl+C to stop):
gamepulse-agent

# Background (PowerShell job):
$j = Start-Job { gamepulse-agent }
# ... play ...
Stop-Job $j; Remove-Job $j

Configuration

The agent searches for config in this order (first found wins):

Linux:

$GAMEPULSE_CONFIG env var (full path)
~/.config/gamepulse/gamepulse.toml
/etc/gamepulse/gamepulse.toml

Windows:

%GAMEPULSE_CONFIG% env var (full path)
%APPDATA%\GamePulse\gamepulse.toml (per-user — recommended)
%PROGRAMDATA%\GamePulse\gamepulse.toml (system-wide, all users)

The MSI installs a starting template at C:\Program Files\GamePulse\config\gamepulse.toml.example — copy it to one of the locations above and fill in your endpoint + API key.

Minimal config:

[elasticsearch]
endpoint = "https://your-project.es.us-central1.gcp.elastic.cloud"
api_key  = "your-api-key-here"

You can also pass credentials via environment variables (takes precedence over config):

export ES_URL="https://your-project.es.us-central1.gcp.elastic.cloud"
export ES_API_KEY="your-api-key-here"
gamepulse-agent

Full config reference: gamepulse-agent --help and the example at /etc/gamepulse/gamepulse.toml.

Game Profiles

GamePulse ships three starter profiles that auto-apply when the matching game is detected:

Game	Steam App ID	Auto-configured
Starfield	1716740	FSR 2, ray tracing, ultra preset
Cyberpunk 2077	1091500	DLSS / FSR 3 / XeSS, path tracing
Baldur's Gate 3	1086940	Vulkan

Profiles live at /usr/share/gamepulse/profiles/ (system) or ~/.config/gamepulse/profiles/ (user, takes precedence). Copy and edit one to create your own.

Troubleshooting

"No Elasticsearch endpoint configured"
Run gamepulse setup or set ES_URL and ES_API_KEY environment variables.

"ES ping failed" at startup
Check that your API key is valid and the endpoint URL ends in .es. (not .kb.). Run gamepulse-agent diagnose for a full connectivity report.

Agent doesn't detect my game
The agent detects Steam games automatically. For non-Steam games (Lutris, Heroic, Bottles) detection is also automatic. For anything else, pin the target manually:

gamepulse-agent --target-name "MyGame"
# or
gamepulse-agent --target-pid 12345

Permissions error on /proc
The agent reads /proc/<pid>/maps and /proc/<pid>/environ for settings auto-detection. This works without elevated privileges on standard desktop kernels. If you have a hardened kernel with restricted /proc access, run gamepulse-agent --log-level debug to see which reads are failing.

systemd unit fails to start
If you installed a dev build to /usr/local/bin/ instead of /usr/bin/, the unit's ExecStart path won't match. Create a drop-in override:

mkdir -p ~/.config/systemd/user/gamepulse-agent.service.d
cat > ~/.config/systemd/user/gamepulse-agent.service.d/override.conf <<EOF
[Service]
ExecStart=
ExecStart=/usr/local/bin/gamepulse-agent
EOF
systemctl --user daemon-reload

FAQ

Assets 9

08 May 17:17

github-actions

v0.1.3

42c4378

v0.1.3

What's in this release

Linux packages (.deb, .rpm, .pkg.tar.zst):

gamepulse-agent — the telemetry agent binary
gamepulse — unified launcher CLI (setup / start / stop / status / run %command%)
systemd user unit (gamepulse-agent.service)
Example config at /etc/gamepulse/gamepulse.toml
Three starter game profiles (Starfield, Cyberpunk 2077, Baldur's Gate 3)

Windows package (.msi):

gamepulse-agent.exe installed to C:\Program Files\GamePulse\bin\ (added to system PATH)
Example config at C:\Program Files\GamePulse\config\gamepulse.toml.example
Three starter game profiles at C:\Program Files\GamePulse\profiles\

eBPF probes (deep kernel-level GPU/CPU scheduler, block I/O, futex, VFS metrics) are not included in these packages — they require a nightly Rust toolchain and bpf-linker, and are Linux-only. Arch/CachyOS users who want eBPF should install from AUR (yay -S gamepulse-git) which builds everything from source. Windows is an eBPF-equivalent-free build by design.

Requirements

Linux x86_64, glibc 2.39+ (Ubuntu 24.04, Fedora 40, Arch, CachyOS, SteamOS 3.6+) — full feature set
Windows 10 / 11 x86_64 — agent only, no eBPF; some metrics partial (see "Windows caveats" below)
An Elasticsearch endpoint — the free tier on Elastic Cloud Serverless works
An API key with write access to metrics-gamepulse.* data streams (see Quick Start)
MangoHud (Linux) / PresentMon (Windows) — optional, required for frame timing (gamepulse.fps.* fields)

Installation

Arch Linux / CachyOS / Manjaro

Install the pre-built package from this release:

sudo pacman -U gamepulse-0.1.0-1-x86_64.pkg.tar.zst

Or install from AUR (includes eBPF probes, builds from source):

yay -S gamepulse-git

Debian / Ubuntu (24.04+)

sudo dpkg -i gamepulse-agent_0.1.0-1_amd64.deb

Fedora / RHEL / openSUSE

sudo rpm -i gamepulse-agent-0.1.0-1.x86_64.rpm

Windows 10 / 11

Double-click the .msi and accept the UAC prompt, or install silently from an admin PowerShell:

msiexec /i gamepulse-agent-0.1.0-x86_64.msi /qb!

The installer adds C:\Program Files\GamePulse\bin\ to the system PATH. Open a new terminal so gamepulse-agent is on PATH:

gamepulse-agent --version

To uninstall:

msiexec /x gamepulse-agent-0.1.0-x86_64.msi /qb!

or use Settings → Apps → Installed apps → GamePulse → Uninstall.

Windows caveats

No gamepulse launcher CLI — Windows has no systemd analog. Configure the agent by hand and run gamepulse-agent directly (or wrap it in a Steam launch option, see Quick Start §5).
gpu.temperature_c is reported via WMI ACPI thermal zones (best-effort, may be absent on some boards).
cpu.game_utilisation_pct, storage.game_io, audio.xruns, power.battery_rate_w are not populated on Windows in this release — the Linux equivalents require eBPF / hwmon / pw-top, which have no direct Windows counterpart yet.
Frame timing requires PresentMon. Place PresentMon.exe on PATH or set GAMEPULSE_PRESENTMON=C:\path\to\PresentMon.exe. Without it, all other 7 collectors continue normally and gamepulse.fps.* fields are empty.

Quick Start

1. Get an Elasticsearch endpoint

Sign up for a free Elastic Cloud Serverless project. Copy the Elasticsearch endpoint URL from the project overview — it looks like https://your-project.es.us-central1.gcp.elastic.cloud.

2. Create an API key

In Kibana → Stack Management → API Keys, create a key with these privileges:

Index privileges: create_index, create, write, view_index_metadata on metrics-gamepulse.*
Cluster privileges: monitor

3. Run first-time setup

Linux:

gamepulse setup

Writes endpoint + API key to ~/.config/gamepulse/gamepulse.toml and verifies connectivity.

Windows (no gamepulse setup yet — manual config):

$cfgDir = "$env:APPDATA\GamePulse"
New-Item -ItemType Directory -Force -Path $cfgDir | Out-Null
Copy-Item "C:\Program Files\GamePulse\config\gamepulse.toml.example" "$cfgDir\gamepulse.toml"
notepad "$cfgDir\gamepulse.toml"   # fill in endpoint + api_key, save

Or skip the file and use environment variables (Windows + Linux both honour these):

[Environment]::SetEnvironmentVariable('ES_URL',     'https://your-project.es.us-central1.gcp.elastic.cloud', 'User')
[Environment]::SetEnvironmentVariable('ES_API_KEY', 'your-api-key-here',                                      'User')

4. Test with a dry run

gamepulse-agent --dry-run

You should see your hardware snapshot (CPU model, GPU, RAM) printed and collectors ready in the log. No data is written to Elasticsearch in dry-run mode.

5. Steam integration (Linux, recommended)

In Steam, right-click a game → Properties → Launch Options:

gamepulse run %command%

The agent starts automatically when the game launches and stops cleanly when you quit. Session data appears in Elasticsearch within a few seconds.

Windows: the launcher script is Linux-only in this release. Run gamepulse-agent.exe from any terminal before launching the game; it auto-detects Steam, Lutris, Heroic, Bottles, or use --target-name <ProcessName> / --target-pid <PID> to pin a specific process.

6. Manual start / stop

Linux (systemd-managed):

gamepulse start    # start the agent in the background via systemd
gamepulse status   # show current session label and service state
gamepulse stop     # stop the agent gracefully

Windows (no service yet — run the binary directly):

# Foreground (Ctrl+C to stop):
gamepulse-agent

# Background (PowerShell job):
$j = Start-Job { gamepulse-agent }
# ... play ...
Stop-Job $j; Remove-Job $j

Configuration

The agent searches for config in this order (first found wins):

Linux:

$GAMEPULSE_CONFIG env var (full path)
~/.config/gamepulse/gamepulse.toml
/etc/gamepulse/gamepulse.toml

Windows:

%GAMEPULSE_CONFIG% env var (full path)
%APPDATA%\GamePulse\gamepulse.toml (per-user — recommended)
%PROGRAMDATA%\GamePulse\gamepulse.toml (system-wide, all users)

The MSI installs a starting template at C:\Program Files\GamePulse\config\gamepulse.toml.example — copy it to one of the locations above and fill in your endpoint + API key.

Minimal config:

[elasticsearch]
endpoint = "https://your-project.es.us-central1.gcp.elastic.cloud"
api_key  = "your-api-key-here"

You can also pass credentials via environment variables (takes precedence over config):

export ES_URL="https://your-project.es.us-central1.gcp.elastic.cloud"
export ES_API_KEY="your-api-key-here"
gamepulse-agent

Full config reference: gamepulse-agent --help and the example at /etc/gamepulse/gamepulse.toml.

Game Profiles

GamePulse ships three starter profiles that auto-apply when the matching game is detected:

Game	Steam App ID	Auto-configured
Starfield	1716740	FSR 2, ray tracing, ultra preset
Cyberpunk 2077	1091500	DLSS / FSR 3 / XeSS, path tracing
Baldur's Gate 3	1086940	Vulkan

Profiles live at /usr/share/gamepulse/profiles/ (system) or ~/.config/gamepulse/profiles/ (user, takes precedence). Copy and edit one to create your own.

Troubleshooting

"No Elasticsearch endpoint configured"
Run gamepulse setup or set ES_URL and ES_API_KEY environment variables.

"ES ping failed" at startup
Check that your API key is valid and the endpoint URL ends in .es. (not .kb.). Run gamepulse-agent diagnose for a full connectivity report.

Agent doesn't detect my game
The agent detects Steam games automatically. For non-Steam games (Lutris, Heroic, Bottles) detection is also automatic. For anything else, pin the target manually:

gamepulse-agent --target-name "MyGame"
# or
gamepulse-agent --target-pid 12345

Permissions error on /proc
The agent reads /proc/<pid>/maps and /proc/<pid>/environ for settings auto-detection. This works without elevated privileges on standard desktop kernels. If you have a hardened kernel with restricted /proc access, run gamepulse-agent --log-level debug to see which reads are failing.

systemd unit fails to start
If you installed a dev build to /usr/local/bin/ instead of /usr/bin/, the unit's ExecStart path won't match. Create a drop-in override:

mkdir -p ~/.config/systemd/user/gamepulse-agent.service.d
cat > ~/.config/systemd/user/gamepulse-agent.service.d/override.conf <<EOF
[Service]
ExecStart=
ExecStart=/usr/local/bin/gamepulse-agent
EOF
systemctl --user daemon-reload

FAQ

Assets 9

08 May 13:49

github-actions

v0.1.2

b03a7c0

v0.1.2

What's in this release

Linux packages (.deb, .rpm, .pkg.tar.zst):

gamepulse-agent — the telemetry agent binary
gamepulse — unified launcher CLI (setup / start / stop / status / run %command%)
systemd user unit (gamepulse-agent.service)
Example config at /etc/gamepulse/gamepulse.toml
Three starter game profiles (Starfield, Cyberpunk 2077, Baldur's Gate 3)

Windows package (.msi):

gamepulse-agent.exe installed to C:\Program Files\GamePulse\bin\ (added to system PATH)
Example config at C:\Program Files\GamePulse\config\gamepulse.toml.example
Three starter game profiles at C:\Program Files\GamePulse\profiles\

eBPF probes (deep kernel-level GPU/CPU scheduler, block I/O, futex, VFS metrics) are not included in these packages — they require a nightly Rust toolchain and bpf-linker, and are Linux-only. Arch/CachyOS users who want eBPF should install from AUR (yay -S gamepulse-git) which builds everything from source. Windows is an eBPF-equivalent-free build by design.

Requirements

Linux x86_64, glibc 2.39+ (Ubuntu 24.04, Fedora 40, Arch, CachyOS, SteamOS 3.6+) — full feature set
Windows 10 / 11 x86_64 — agent only, no eBPF; some metrics partial (see "Windows caveats" below)
An Elasticsearch endpoint — the free tier on Elastic Cloud Serverless works
An API key with write access to metrics-gamepulse.* data streams (see Quick Start)
MangoHud (Linux) / PresentMon (Windows) — optional, required for frame timing (gamepulse.fps.* fields)

Installation

Arch Linux / CachyOS / Manjaro

Install the pre-built package from this release:

sudo pacman -U gamepulse-0.1.0-1-x86_64.pkg.tar.zst

Or install from AUR (includes eBPF probes, builds from source):

yay -S gamepulse-git

Debian / Ubuntu (24.04+)

sudo dpkg -i gamepulse-agent_0.1.0-1_amd64.deb

Fedora / RHEL / openSUSE

sudo rpm -i gamepulse-agent-0.1.0-1.x86_64.rpm

Windows 10 / 11

Double-click the .msi and accept the UAC prompt, or install silently from an admin PowerShell:

msiexec /i gamepulse-agent-0.1.0-x86_64.msi /qb!

The installer adds C:\Program Files\GamePulse\bin\ to the system PATH. Open a new terminal so gamepulse-agent is on PATH:

gamepulse-agent --version

To uninstall:

msiexec /x gamepulse-agent-0.1.0-x86_64.msi /qb!

or use Settings → Apps → Installed apps → GamePulse → Uninstall.

Windows caveats

No gamepulse launcher CLI — Windows has no systemd analog. Configure the agent by hand and run gamepulse-agent directly (or wrap it in a Steam launch option, see Quick Start §5).
gpu.temperature_c is reported via WMI ACPI thermal zones (best-effort, may be absent on some boards).
cpu.game_utilisation_pct, storage.game_io, audio.xruns, power.battery_rate_w are not populated on Windows in this release — the Linux equivalents require eBPF / hwmon / pw-top, which have no direct Windows counterpart yet.
Frame timing requires PresentMon. Place PresentMon.exe on PATH or set GAMEPULSE_PRESENTMON=C:\path\to\PresentMon.exe. Without it, all other 7 collectors continue normally and gamepulse.fps.* fields are empty.

Quick Start

1. Get an Elasticsearch endpoint

Sign up for a free Elastic Cloud Serverless project. Copy the Elasticsearch endpoint URL from the project overview — it looks like https://your-project.es.us-central1.gcp.elastic.cloud.

2. Create an API key

In Kibana → Stack Management → API Keys, create a key with these privileges:

Index privileges: create_index, create, write, view_index_metadata on metrics-gamepulse.*
Cluster privileges: monitor

3. Run first-time setup

Linux:

gamepulse setup

Writes endpoint + API key to ~/.config/gamepulse/gamepulse.toml and verifies connectivity.

Windows (no gamepulse setup yet — manual config):

$cfgDir = "$env:APPDATA\GamePulse"
New-Item -ItemType Directory -Force -Path $cfgDir | Out-Null
Copy-Item "C:\Program Files\GamePulse\config\gamepulse.toml.example" "$cfgDir\gamepulse.toml"
notepad "$cfgDir\gamepulse.toml"   # fill in endpoint + api_key, save

Or skip the file and use environment variables (Windows + Linux both honour these):

[Environment]::SetEnvironmentVariable('ES_URL',     'https://your-project.es.us-central1.gcp.elastic.cloud', 'User')
[Environment]::SetEnvironmentVariable('ES_API_KEY', 'your-api-key-here',                                      'User')

4. Test with a dry run

gamepulse-agent --dry-run

You should see your hardware snapshot (CPU model, GPU, RAM) printed and collectors ready in the log. No data is written to Elasticsearch in dry-run mode.

5. Steam integration (Linux, recommended)

In Steam, right-click a game → Properties → Launch Options:

gamepulse run %command%

The agent starts automatically when the game launches and stops cleanly when you quit. Session data appears in Elasticsearch within a few seconds.

Windows: the launcher script is Linux-only in this release. Run gamepulse-agent.exe from any terminal before launching the game; it auto-detects Steam, Lutris, Heroic, Bottles, or use --target-name <ProcessName> / --target-pid <PID> to pin a specific process.

6. Manual start / stop

Linux (systemd-managed):

gamepulse start    # start the agent in the background via systemd
gamepulse status   # show current session label and service state
gamepulse stop     # stop the agent gracefully

Windows (no service yet — run the binary directly):

# Foreground (Ctrl+C to stop):
gamepulse-agent

# Background (PowerShell job):
$j = Start-Job { gamepulse-agent }
# ... play ...
Stop-Job $j; Remove-Job $j

Configuration

The agent searches for config in this order (first found wins):

Linux:

$GAMEPULSE_CONFIG env var (full path)
~/.config/gamepulse/gamepulse.toml
/etc/gamepulse/gamepulse.toml

Windows:

%GAMEPULSE_CONFIG% env var (full path)
%APPDATA%\GamePulse\gamepulse.toml (per-user — recommended)
%PROGRAMDATA%\GamePulse\gamepulse.toml (system-wide, all users)

The MSI installs a starting template at C:\Program Files\GamePulse\config\gamepulse.toml.example — copy it to one of the locations above and fill in your endpoint + API key.

Minimal config:

[elasticsearch]
endpoint = "https://your-project.es.us-central1.gcp.elastic.cloud"
api_key  = "your-api-key-here"

You can also pass credentials via environment variables (takes precedence over config):

export ES_URL="https://your-project.es.us-central1.gcp.elastic.cloud"
export ES_API_KEY="your-api-key-here"
gamepulse-agent

Full config reference: gamepulse-agent --help and the example at /etc/gamepulse/gamepulse.toml.

Game Profiles

GamePulse ships three starter profiles that auto-apply when the matching game is detected:

Game	Steam App ID	Auto-configured
Starfield	1716740	FSR 2, ray tracing, ultra preset
Cyberpunk 2077	1091500	DLSS / FSR 3 / XeSS, path tracing
Baldur's Gate 3	1086940	Vulkan

Profiles live at /usr/share/gamepulse/profiles/ (system) or ~/.config/gamepulse/profiles/ (user, takes precedence). Copy and edit one to create your own.

Troubleshooting

"No Elasticsearch endpoint configured"
Run gamepulse setup or set ES_URL and ES_API_KEY environment variables.

"ES ping failed" at startup
Check that your API key is valid and the endpoint URL ends in .es. (not .kb.). Run gamepulse-agent diagnose for a full connectivity report.

Agent doesn't detect my game
The agent detects Steam games automatically. For non-Steam games (Lutris, Heroic, Bottles) detection is also automatic. For anything else, pin the target manually:

gamepulse-agent --target-name "MyGame"
# or
gamepulse-agent --target-pid 12345

Permissions error on /proc
The agent reads /proc/<pid>/maps and /proc/<pid>/environ for settings auto-detection. This works without elevated privileges on standard desktop kernels. If you have a hardened kernel with restricted /proc access, run gamepulse-agent --log-level debug to see which reads are failing.

systemd unit fails to start
If you installed a dev build to /usr/local/bin/ instead of /usr/bin/, the unit's ExecStart path won't match. Create a drop-in override:

mkdir -p ~/.config/systemd/user/gamepulse-agent.service.d
cat > ~/.config/systemd/user/gamepulse-agent.service.d/override.conf <<EOF
[Service]
ExecStart=
ExecStart=/usr/local/bin/gamepulse-agent
EOF
systemctl --user daemon-reload

FAQ

Assets 9

07 May 13:46

github-actions

v0.1.0

3799c5c

v0.1.0

What's in this release

Linux packages (.deb, .rpm, .pkg.tar.zst):

gamepulse-agent — the telemetry agent binary
gamepulse — unified launcher CLI (setup / start / stop / status / run %command%)
systemd user unit (gamepulse-agent.service)
Example config at /etc/gamepulse/gamepulse.toml
Three starter game profiles (Starfield, Cyberpunk 2077, Baldur's Gate 3)

Windows package (.msi):

gamepulse-agent.exe installed to C:\Program Files\GamePulse\bin\ (added to system PATH)
Example config at C:\Program Files\GamePulse\config\gamepulse.toml.example
Three starter game profiles at C:\Program Files\GamePulse\profiles\

eBPF probes (deep kernel-level GPU/CPU scheduler, block I/O, futex, VFS metrics) are not included in these packages — they require a nightly Rust toolchain and bpf-linker, and are Linux-only. Arch/CachyOS users who want eBPF should install from AUR (yay -S gamepulse-git) which builds everything from source. Windows is an eBPF-equivalent-free build by design.

Requirements

Linux x86_64, glibc 2.39+ (Ubuntu 24.04, Fedora 40, Arch, CachyOS, SteamOS 3.6+) — full feature set
Windows 10 / 11 x86_64 — agent only, no eBPF; some metrics partial (see "Windows caveats" below)
An Elasticsearch endpoint — the free tier on Elastic Cloud Serverless works
An API key with write access to metrics-gamepulse.* data streams (see Quick Start)
MangoHud (Linux) / PresentMon (Windows) — optional, required for frame timing (gamepulse.fps.* fields)

Installation

Arch Linux / CachyOS / Manjaro

Install the pre-built package from this release:

sudo pacman -U gamepulse-0.1.0-1-x86_64.pkg.tar.zst

Or install from AUR (includes eBPF probes, builds from source):

yay -S gamepulse-git

Debian / Ubuntu (24.04+)

sudo dpkg -i gamepulse-agent_0.1.0-1_amd64.deb

Fedora / RHEL / openSUSE

sudo rpm -i gamepulse-agent-0.1.0-1.x86_64.rpm

Windows 10 / 11

Double-click the .msi and accept the UAC prompt, or install silently from an admin PowerShell:

msiexec /i gamepulse-agent-0.1.0-x86_64.msi /qb!

The installer adds C:\Program Files\GamePulse\bin\ to the system PATH. Open a new terminal so gamepulse-agent is on PATH:

gamepulse-agent --version

To uninstall:

msiexec /x gamepulse-agent-0.1.0-x86_64.msi /qb!

or use Settings → Apps → Installed apps → GamePulse → Uninstall.

Windows caveats

No gamepulse launcher CLI — Windows has no systemd analog. Configure the agent by hand and run gamepulse-agent directly (or wrap it in a Steam launch option, see Quick Start §5).
gpu.temperature_c is reported via WMI ACPI thermal zones (best-effort, may be absent on some boards).
cpu.game_utilisation_pct, storage.game_io, audio.xruns, power.battery_rate_w are not populated on Windows in this release — the Linux equivalents require eBPF / hwmon / pw-top, which have no direct Windows counterpart yet.
Frame timing requires PresentMon. Place PresentMon.exe on PATH or set GAMEPULSE_PRESENTMON=C:\path\to\PresentMon.exe. Without it, all other 7 collectors continue normally and gamepulse.fps.* fields are empty.

Quick Start

1. Get an Elasticsearch endpoint

Sign up for a free Elastic Cloud Serverless project. Copy the Elasticsearch endpoint URL from the project overview — it looks like https://your-project.es.us-central1.gcp.elastic.cloud.

2. Create an API key

In Kibana → Stack Management → API Keys, create a key with these privileges:

Index privileges: create_index, create, write, view_index_metadata on metrics-gamepulse.*
Cluster privileges: monitor

3. Run first-time setup

Linux:

gamepulse setup

Writes endpoint + API key to ~/.config/gamepulse/gamepulse.toml and verifies connectivity.

Windows (no gamepulse setup yet — manual config):

$cfgDir = "$env:APPDATA\GamePulse"
New-Item -ItemType Directory -Force -Path $cfgDir | Out-Null
Copy-Item "C:\Program Files\GamePulse\config\gamepulse.toml.example" "$cfgDir\gamepulse.toml"
notepad "$cfgDir\gamepulse.toml"   # fill in endpoint + api_key, save

Or skip the file and use environment variables (Windows + Linux both honour these):

[Environment]::SetEnvironmentVariable('ES_URL',     'https://your-project.es.us-central1.gcp.elastic.cloud', 'User')
[Environment]::SetEnvironmentVariable('ES_API_KEY', 'your-api-key-here',                                      'User')

4. Test with a dry run

gamepulse-agent --dry-run

You should see your hardware snapshot (CPU model, GPU, RAM) printed and collectors ready in the log. No data is written to Elasticsearch in dry-run mode.

5. Steam integration (Linux, recommended)

In Steam, right-click a game → Properties → Launch Options:

gamepulse run %command%

The agent starts automatically when the game launches and stops cleanly when you quit. Session data appears in Elasticsearch within a few seconds.

Windows: the launcher script is Linux-only in this release. Run gamepulse-agent.exe from any terminal before launching the game; it auto-detects Steam, Lutris, Heroic, Bottles, or use --target-name <ProcessName> / --target-pid <PID> to pin a specific process.

6. Manual start / stop

Linux (systemd-managed):

gamepulse start    # start the agent in the background via systemd
gamepulse status   # show current session label and service state
gamepulse stop     # stop the agent gracefully

Windows (no service yet — run the binary directly):

# Foreground (Ctrl+C to stop):
gamepulse-agent

# Background (PowerShell job):
$j = Start-Job { gamepulse-agent }
# ... play ...
Stop-Job $j; Remove-Job $j

Configuration

The agent searches for config in this order (first found wins):

Linux:

$GAMEPULSE_CONFIG env var (full path)
~/.config/gamepulse/gamepulse.toml
/etc/gamepulse/gamepulse.toml

Windows:

%GAMEPULSE_CONFIG% env var (full path)
%APPDATA%\GamePulse\gamepulse.toml (per-user — recommended)
%PROGRAMDATA%\GamePulse\gamepulse.toml (system-wide, all users)

The MSI installs a starting template at C:\Program Files\GamePulse\config\gamepulse.toml.example — copy it to one of the locations above and fill in your endpoint + API key.

Minimal config:

[elasticsearch]
endpoint = "https://your-project.es.us-central1.gcp.elastic.cloud"
api_key  = "your-api-key-here"

You can also pass credentials via environment variables (takes precedence over config):

export ES_URL="https://your-project.es.us-central1.gcp.elastic.cloud"
export ES_API_KEY="your-api-key-here"
gamepulse-agent

Full config reference: gamepulse-agent --help and the example at /etc/gamepulse/gamepulse.toml.

Game Profiles

GamePulse ships three starter profiles that auto-apply when the matching game is detected:

Game	Steam App ID	Auto-configured
Starfield	1716740	FSR 2, ray tracing, ultra preset
Cyberpunk 2077	1091500	DLSS / FSR 3 / XeSS, path tracing
Baldur's Gate 3	1086940	Vulkan

Profiles live at /usr/share/gamepulse/profiles/ (system) or ~/.config/gamepulse/profiles/ (user, takes precedence). Copy and edit one to create your own.

Troubleshooting

"No Elasticsearch endpoint configured"
Run gamepulse setup or set ES_URL and ES_API_KEY environment variables.

"ES ping failed" at startup
Check that your API key is valid and the endpoint URL ends in .es. (not .kb.). Run gamepulse-agent diagnose for a full connectivity report.

Agent doesn't detect my game
The agent detects Steam games automatically. For non-Steam games (Lutris, Heroic, Bottles) detection is also automatic. For anything else, pin the target manually:

gamepulse-agent --target-name "MyGame"
# or
gamepulse-agent --target-pid 12345

Permissions error on /proc
The agent reads /proc/<pid>/maps and /proc/<pid>/environ for settings auto-detection. This works without elevated privileges on standard desktop kernels. If you have a hardened kernel with restricted /proc access, run gamepulse-agent --log-level debug to see which reads are failing.

systemd unit fails to start
If you installed a dev build to /usr/local/bin/ instead of /usr/bin/, the unit's ExecStart path won't match. Create a drop-in override:

mkdir -p ~/.config/systemd/user/gamepulse-agent.service.d
cat > ~/.config/systemd/user/gamepulse-agent.service.d/override.conf <<EOF
[Service]
ExecStart=
ExecStart=/usr/local/bin/gamepulse-agent
EOF
systemctl --user daemon-reload

FAQ

Assets 7

06 May 19:58

github-actions

v0.1.1

cb271b8

v0.1.1

What's in this release

Linux packages (.deb, .rpm, .pkg.tar.zst):

gamepulse-agent — the telemetry agent binary
gamepulse — unified launcher CLI (setup / start / stop / status / run %command%)
systemd user unit (gamepulse-agent.service)
Example config at /etc/gamepulse/gamepulse.toml
Three starter game profiles (Starfield, Cyberpunk 2077, Baldur's Gate 3)

Windows package (.msi):

gamepulse-agent.exe installed to C:\Program Files\GamePulse\bin\ (added to system PATH)
Example config at C:\Program Files\GamePulse\config\gamepulse.toml.example
Three starter game profiles at C:\Program Files\GamePulse\profiles\

eBPF probes (deep kernel-level GPU/CPU scheduler, block I/O, futex, VFS metrics) are not included in these packages — they require a nightly Rust toolchain and bpf-linker, and are Linux-only. Arch/CachyOS users who want eBPF should install from AUR (yay -S gamepulse-git) which builds everything from source. Windows is an eBPF-equivalent-free build by design.

Requirements

Linux x86_64, glibc 2.39+ (Ubuntu 24.04, Fedora 40, Arch, CachyOS, SteamOS 3.6+) — full feature set
Windows 10 / 11 x86_64 — agent only, no eBPF; some metrics partial (see "Windows caveats" below)
An Elasticsearch endpoint — the free tier on Elastic Cloud Serverless works
An API key with write access to metrics-gamepulse.* data streams (see Quick Start)
MangoHud (Linux) / PresentMon (Windows) — optional, required for frame timing (gamepulse.fps.* fields)

Installation

Arch Linux / CachyOS / Manjaro

Install the pre-built package from this release:

sudo pacman -U gamepulse-0.1.0-1-x86_64.pkg.tar.zst

Or install from AUR (includes eBPF probes, builds from source):

yay -S gamepulse-git

Debian / Ubuntu (24.04+)

sudo dpkg -i gamepulse-agent_0.1.0-1_amd64.deb

Fedora / RHEL / openSUSE

sudo rpm -i gamepulse-agent-0.1.0-1.x86_64.rpm

Windows 10 / 11

Double-click the .msi and accept the UAC prompt, or install silently from an admin PowerShell:

msiexec /i gamepulse-agent-0.1.0-x86_64.msi /qb!

The installer adds C:\Program Files\GamePulse\bin\ to the system PATH. Open a new terminal so gamepulse-agent is on PATH:

gamepulse-agent --version

To uninstall:

msiexec /x gamepulse-agent-0.1.0-x86_64.msi /qb!

or use Settings → Apps → Installed apps → GamePulse → Uninstall.

Windows caveats

No gamepulse launcher CLI — Windows has no systemd analog. Configure the agent by hand and run gamepulse-agent directly (or wrap it in a Steam launch option, see Quick Start §5).
gpu.temperature_c is reported via WMI ACPI thermal zones (best-effort, may be absent on some boards).
cpu.game_utilisation_pct, storage.game_io, audio.xruns, power.battery_rate_w are not populated on Windows in this release — the Linux equivalents require eBPF / hwmon / pw-top, which have no direct Windows counterpart yet.
Frame timing requires PresentMon. Place PresentMon.exe on PATH or set GAMEPULSE_PRESENTMON=C:\path\to\PresentMon.exe. Without it, all other 7 collectors continue normally and gamepulse.fps.* fields are empty.

Quick Start

1. Get an Elasticsearch endpoint

Sign up for a free Elastic Cloud Serverless project. Copy the Elasticsearch endpoint URL from the project overview — it looks like https://your-project.es.us-central1.gcp.elastic.cloud.

2. Create an API key

In Kibana → Stack Management → API Keys, create a key with these privileges:

Index privileges: create_index, create, write, view_index_metadata on metrics-gamepulse.*
Cluster privileges: monitor

3. Run first-time setup

Linux:

gamepulse setup

Writes endpoint + API key to ~/.config/gamepulse/gamepulse.toml and verifies connectivity.

Windows (no gamepulse setup yet — manual config):

$cfgDir = "$env:APPDATA\GamePulse"
New-Item -ItemType Directory -Force -Path $cfgDir | Out-Null
Copy-Item "C:\Program Files\GamePulse\config\gamepulse.toml.example" "$cfgDir\gamepulse.toml"
notepad "$cfgDir\gamepulse.toml"   # fill in endpoint + api_key, save

Or skip the file and use environment variables (Windows + Linux both honour these):

[Environment]::SetEnvironmentVariable('ES_URL',     'https://your-project.es.us-central1.gcp.elastic.cloud', 'User')
[Environment]::SetEnvironmentVariable('ES_API_KEY', 'your-api-key-here',                                      'User')

4. Test with a dry run

gamepulse-agent --dry-run

You should see your hardware snapshot (CPU model, GPU, RAM) printed and collectors ready in the log. No data is written to Elasticsearch in dry-run mode.

5. Steam integration (Linux, recommended)

In Steam, right-click a game → Properties → Launch Options:

gamepulse run %command%

The agent starts automatically when the game launches and stops cleanly when you quit. Session data appears in Elasticsearch within a few seconds.

Windows: the launcher script is Linux-only in this release. Run gamepulse-agent.exe from any terminal before launching the game; it auto-detects Steam, Lutris, Heroic, Bottles, or use --target-name <ProcessName> / --target-pid <PID> to pin a specific process.

6. Manual start / stop

Linux (systemd-managed):

gamepulse start    # start the agent in the background via systemd
gamepulse status   # show current session label and service state
gamepulse stop     # stop the agent gracefully

Windows (no service yet — run the binary directly):

# Foreground (Ctrl+C to stop):
gamepulse-agent

# Background (PowerShell job):
$j = Start-Job { gamepulse-agent }
# ... play ...
Stop-Job $j; Remove-Job $j

Configuration

The agent searches for config in this order (first found wins):

Linux:

$GAMEPULSE_CONFIG env var (full path)
~/.config/gamepulse/gamepulse.toml
/etc/gamepulse/gamepulse.toml

Windows:

%GAMEPULSE_CONFIG% env var (full path)
%APPDATA%\GamePulse\gamepulse.toml (per-user — recommended)
%PROGRAMDATA%\GamePulse\gamepulse.toml (system-wide, all users)

The MSI installs a starting template at C:\Program Files\GamePulse\config\gamepulse.toml.example — copy it to one of the locations above and fill in your endpoint + API key.

Minimal config:

[elasticsearch]
endpoint = "https://your-project.es.us-central1.gcp.elastic.cloud"
api_key  = "your-api-key-here"

You can also pass credentials via environment variables (takes precedence over config):

export ES_URL="https://your-project.es.us-central1.gcp.elastic.cloud"
export ES_API_KEY="your-api-key-here"
gamepulse-agent

Full config reference: gamepulse-agent --help and the example at /etc/gamepulse/gamepulse.toml.

Game Profiles

GamePulse ships three starter profiles that auto-apply when the matching game is detected:

Game	Steam App ID	Auto-configured
Starfield	1716740	FSR 2, ray tracing, ultra preset
Cyberpunk 2077	1091500	DLSS / FSR 3 / XeSS, path tracing
Baldur's Gate 3	1086940	Vulkan

Profiles live at /usr/share/gamepulse/profiles/ (system) or ~/.config/gamepulse/profiles/ (user, takes precedence). Copy and edit one to create your own.

Troubleshooting

"No Elasticsearch endpoint configured"
Run gamepulse setup or set ES_URL and ES_API_KEY environment variables.

"ES ping failed" at startup
Check that your API key is valid and the endpoint URL ends in .es. (not .kb.). Run gamepulse-agent diagnose for a full connectivity report.

Agent doesn't detect my game
The agent detects Steam games automatically. For non-Steam games (Lutris, Heroic, Bottles) detection is also automatic. For anything else, pin the target manually:

gamepulse-agent --target-name "MyGame"
# or
gamepulse-agent --target-pid 12345

Permissions error on /proc
The agent reads /proc/<pid>/maps and /proc/<pid>/environ for settings auto-detection. This works without elevated privileges on standard desktop kernels. If you have a hardened kernel with restricted /proc access, run gamepulse-agent --log-level debug to see which reads are failing.

systemd unit fails to start
If you installed a dev build to /usr/local/bin/ instead of /usr/bin/, the unit's ExecStart path won't match. Create a drop-in override:

mkdir -p ~/.config/systemd/user/gamepulse-agent.service.d
cat > ~/.config/systemd/user/gamepulse-agent.service.d/override.conf <<EOF
[Service]
ExecStart=
ExecStart=/usr/local/bin/gamepulse-agent
EOF
systemctl --user daemon-reload

FAQ

Assets 7

Releases: MathewRJ/RigSignal

v0.2.1

What's in this release

Requirements

Installation

Arch Linux / CachyOS / Manjaro

Debian / Ubuntu (24.04+)

Fedora / RHEL / openSUSE

Windows 10 / 11

Windows caveats

Quick Start

1. Get an Elasticsearch endpoint

2. Create an API key

3. Run first-time setup

4. Test with a dry run

5. Steam integration (Linux, recommended)

6. Manual start / stop

Configuration

Game Profiles

Troubleshooting

FAQ

Contributors

Uh oh!

v0.2.0

What's in this release

Requirements

Installation

Arch Linux / CachyOS / Manjaro

Debian / Ubuntu (24.04+)

Fedora / RHEL / openSUSE

Windows 10 / 11

Windows caveats

Quick Start

1. Get an Elasticsearch endpoint

2. Create an API key

3. Run first-time setup

4. Test with a dry run

5. Steam integration (Linux, recommended)

6. Manual start / stop

Configuration

Game Profiles

Troubleshooting

FAQ

Uh oh!

v0.1.7

What's in this release

Requirements

Installation

Arch Linux / CachyOS / Manjaro

Debian / Ubuntu (24.04+)

Fedora / RHEL / openSUSE

Windows 10 / 11

Windows caveats

Quick Start

1. Get an Elasticsearch endpoint

2. Create an API key

3. Run first-time setup

4. Test with a dry run

5. Steam integration (Linux, recommended)

6. Manual start / stop

Configuration

Game Profiles

Troubleshooting

FAQ

Uh oh!

v0.1.6

What's in this release

Requirements

Installation

Arch Linux / CachyOS / Manjaro

Debian / Ubuntu (24.04+)

Fedora / RHEL / openSUSE

Windows 10 / 11

Windows caveats

Quick Start

1. Get an Elasticsearch endpoint

2. Create an API key

3. Run first-time setup

4. Test with a dry run

5. Steam integration (Linux, recommended)