← Back to StaxPing Index

Config & First‑Run Behavior

StaxPing performs a one‑time setup on first launch to ensure consistent behavior across platforms.
This setup is lightweight, non‑interactive after acceptance, and designed to avoid surprises during normal use.

---

First‑Run Steps

When StaxPing is executed for the first time, it performs the following actions:

1. Displays the EULA
   The user must accept the terms before continuing.

2. Detects the operating system
   Used for capability checks and platform‑specific behavior.

3. Runs capability detection
   Determines which modules (DNS, ICMP, HTTP, traceroute) are supported.

4. Creates a configuration file
   Stored in the user’s home directory for future runs.

After this initial setup, StaxPing runs immediately with no further prompts.

---

Where the Config File Is Stored

The configuration file is intentionally small and platform‑specific.

Linux

$HOME/.config/staxping/config.json

Windows

%APPDATA%\StaxPing\config.json

The directory is created automatically if it does not exist.

---

What’s Inside the Config File

The config file contains only the information required for predictable behavior:

{
  "eula": true,
  "os": "linux",
  "supports_icmp": true,
  "supports_trace": false,
  "supports_dns": true,
  "supports_http": true
}

Notes

• No user data is stored
• No telemetry is collected
• No history or logs are written
• The file is safe to delete at any time

StaxPing regenerates the config on the next run if it is missing.

---

How to Reset the Config

If you want to re‑run the first‑run setup:

1. Delete the config file
2. Run staxping again

StaxPing will recreate the file and repeat capability detection.

This is useful when:

• moving between systems
• changing permissions
• enabling or disabling ICMP capabilities
• testing different environments

---

How Capability Detection Works

Capability detection ensures StaxPing behaves consistently across platforms.

What it checks

• DNS — resolver availability
• ICMP — raw socket permissions or OS‑level restrictions
• HTTP — outbound request capability
• Traceroute — platform support for hop‑based routing

Why it matters

• Prevents unexpected crashes
• Avoids running unsupported modules
• Ensures clean fallback messages
• Keeps output predictable

When it runs

• Automatically on first run
• Automatically if the config file is missing
• Manually if the user deletes the config

---

OS‑Specific Notes

Linux

• ICMP may require elevated capabilities depending on the distribution
• Traceroute support varies between distros
• .deb and AppImage builds behave identically once running

Windows

• ICMP behavior differs from Linux and may require system permissions
• Config is stored in %APPDATA%
• Traceroute support will be added once Windows builds stabilize

macOS (Future)

• Not currently supported
• Capability detection will be adapted if macOS support is introduced

---

StaxPing’s configuration system is intentionally minimal, ensuring a clean, predictable experience across all supported platforms.

---