All posts
tutoriallinux

Monitor a Linux server with OxiPulse

By SecuryBlack

OxiPulse installs on any 64-bit Linux distribution with a single command. The binary is statically linked — no runtime dependencies, no package manager required after installation.

Prerequisites

  • A 64-bit Linux server (Debian, Ubuntu, RHEL, Alpine, or any systemd-based distro)
  • curl installed
  • An OxiPulse account at app.securyblack.com — or your own OTLP ingestor

1. Run the installer

curl -fsSL https://install.oxipulse.dev | sudo bash

The installer:

  • Detects your architecture (x86_64 or ARM64)
  • Downloads the correct static binary from GitHub Releases
  • Installs it to /usr/local/bin/oxipulse
  • Creates the config directory at /etc/oxipulse/
  • Registers and starts the oxipulse systemd service
To review the installer before running it, fetch it first: `curl -fsSL https://install.oxipulse.dev -o install.sh && less install.sh`

2. Create an agent in SecuryBlack

Log into app.securyblack.com, navigate to Agents, and click New agent. Give it a descriptive name (e.g. web-prod-01) and copy the token shown.

The token is shown only once. Copy it before closing the dialog.

3. Configure the agent

sudo nano /etc/oxipulse/config.toml
endpoint = "https://ingest.securyblack.com:4317"
token    = "YOUR_TOKEN_HERE"

# Optional
interval_secs   = 10    # collection interval in seconds (default: 10)
buffer_max_size = 8640  # offline buffer — 24 h at 10 s (default)

4. Restart the agent

sudo systemctl restart oxipulse
sudo systemctl status oxipulse

The output should show Active: active (running).

5. Check the logs

sudo journalctl -fu oxipulse

You should see lines like:

INFO oxipulse: OxiPulse v0.1.10 starting
INFO oxipulse: config loaded endpoint=https://ingest.securyblack.com:4317 interval_secs=10
INFO oxipulse: OTLP exporter initialised
INFO oxipulse: metrics collected and recorded cpu=3.2% ram_used_mb=1024

6. Verify in the dashboard

Open the agent detail page in SecuryBlack. Within 10–30 seconds you should see CPU, RAM, disk and network charts populating with live data.

Configuration via environment variables

If you prefer not to write a config file (useful in Docker or CI environments), all settings can be passed as environment variables:

OXIPULSE_ENDPOINT="https://ingest.securyblack.com:4317" \
OXIPULSE_TOKEN="YOUR_TOKEN_HERE" \
oxipulse

Uninstalling

sudo systemctl disable --now oxipulse
sudo rm /usr/local/bin/oxipulse
sudo rm -rf /etc/oxipulse