Skip to content

Documentation

Pulsewise documentation

Install, configure, and operate Pulsewise across your fleet — from one server to hundreds.

Getting Started

Pulsewise is built for teams that run their own VPS or bare-metal Linux servers. You’ll be live in under five minutes — no agents to compile, no schemas to declare, no dashboards to wire.

1. Create your account

Sign up at pulsewise.io with your work email. Confirm via the link we send, then you’re in. The 14-day free trial starts automatically — no card required.

2. Set up your workspace

A workspace holds your servers, alerts, and teammates. Most teams need just one. Spin up additional workspaces only when you want hard separation between environments (e.g. production vs. staging) or between client accounts.

3. Install the agent

Open Settings → Servers → Add Server and copy the install command. It’s pre-baked with your workspace token — paste and run on any Linux box.

curl -fsSL https://get.pulsewise.io/install.sh | sudo bash -s -- --token YOUR_API_TOKEN

The agent installs as a systemd service and begins streaming metrics within 60 seconds. The server appears in your dashboard the moment it phones home.

4. Confirm it’s reporting

From the server, run:

sudo pulsewise status

You’ll see the agent version, connection state, and the workspace it’s reporting to. If anything looks off, jump to Troubleshooting.

Agent Installation

The Pulsewise agent is a single Go binary that runs as a systemd service. It’s tiny (under 15MB RAM, less than 1% CPU) and ships zero telemetry beyond what you can see in the dashboard.

System requirements

  • Linux kernel 4.4 or newer
  • x86_64 or ARM64 CPU
  • 10MB free disk space
  • Outbound HTTPS to api.pulsewise.io (port 443)
  • systemd as the init system

Two ways to install

One-line installer (recommended). The script in Getting Started handles dependency checks, binary download, systemd registration, and bootstrap config in a single step.

Manual install. Use this if your environment blocks curl-piped scripts or if you’re baking the agent into a golden image.

# Download the latest agent
wget https://releases.pulsewise.io/agent/latest/pulsewise-agent-linux-amd64.tar.gz

# Extract and install
tar -xzf pulsewise-agent-linux-amd64.tar.gz
sudo mv pulsewise-agent /usr/local/bin/

# Drop in the config
sudo mkdir -p /etc/pulsewise
sudo cp pulsewise.yml /etc/pulsewise/config.yml

# Enable and start
sudo systemctl enable --now pulsewise-agent

Configuration

The agent reads /etc/pulsewise/config.yml. The fields you’ll touch most often:

# /etc/pulsewise/config.yml
token: "YOUR_API_TOKEN"
interval: 30          # seconds between samples
hostname: ""          # override auto-detected hostname
labels:
  env: production
  team: backend
services:              # services to track health on
  - nginx
  - postgresql
  - redis
  - docker

Updating

sudo pulsewise update

Updates are in-place. Your config and labels are preserved, the service restarts in under a second, and metric collection picks up where it left off.

Uninstalling

sudo pulsewise uninstall

This removes the agent from the box but keeps the server’s history in your workspace. To delete the server entirely, also remove it from Settings → Servers.

Supported Environments

We test against the Linux distributions and providers our customers actually run. If you don’t see yours below, the agent very likely still works — open a support ticket and we’ll confirm.

Operating systems

  • Ubuntu 20.04 / 22.04 / 24.04 LTS
  • Debian 11 (Bullseye) and 12 (Bookworm)
  • CentOS Stream 8 and 9
  • Rocky Linux 8 and 9
  • AlmaLinux 8 and 9
  • Amazon Linux 2 and 2023
  • Fedora 38, 39, 40
  • Arch Linux (rolling)

VPS providers

Any provider that runs a supported distribution will work. The most common in our fleet:

  • DigitalOcean Droplets
  • Hetzner Cloud and Dedicated
  • Vultr Cloud Compute
  • Linode (Akamai Cloud)
  • AWS EC2 and Lightsail
  • Google Cloud Compute Engine
  • OVHcloud
  • Contabo

Containers

The agent automatically detects Docker containers on the host and surfaces per-container status, restart counts, and resource usage. Kubernetes is intentionally out of scope — Pulsewise is built around the VM/VPS workflow, not pod orchestration.

Monitoring Overview

Pulsewise tracks the operational signals that actually predict outages. Everything you see in the dashboard is computed from these metrics — no log ingestion, no APM hooks, no application instrumentation required.

What we collect

  • CPU — overall and per-core utilization
  • Memory — used, available, cached, and swap pressure
  • Disk — capacity, free space, and inode usage per mount
  • Disk I/O — read/write throughput and IOPS
  • Load average — 1, 5, and 15-minute windows
  • Network — bytes in/out per interface
  • Uptime — time since last reboot
  • Service health — running/stopped state for tracked services
  • Top processes — by CPU and memory consumption
  • Docker — per-container status, restarts, and resource usage

Sampling intervals

Lower intervals give you sharper detection but generate more data. Each plan ships with a sensible default:

  • Solo — every 5 minutes
  • Growth — every 30 seconds
  • Scale — every 10 seconds

The dashboard

The fleet view shows every server’s health at a glance. Click into any server for time-series charts, recent incidents, and process-level detail. Filter by group, label, or status — useful when one bad deploy hits a whole tier.

Alert Channels

Alerts are pushed to wherever your team already lives — inbox, Slack, Discord, or your own webhook. Configure channels once at the workspace level, then attach them to any rule.

Email

On every plan. Each email carries the server name, the metric that triggered the rule, current value vs. threshold, and a one-click link into the incident view. Manage recipients under Settings → Alerts → Email.

Slack

Growth and Scale. Connect via OAuth and pick the channel. Alerts arrive as rich messages with severity, the affected server, and a link back to the dashboard — no copy-pasting context.

Discord

Growth and Scale. Paste a Discord webhook URL and you’re done. Alerts post as embeds, color-coded by severity.

Webhooks

Growth and Scale. Send a JSON payload to any endpoint — perfect for PagerDuty, Opsgenie, custom on-call rotations, or in-house tooling.

{
  "event": "alert.triggered",
  "server": "prod-api-01",
  "metric": "cpu_usage",
  "value": 94.2,
  "threshold": 90,
  "severity": "critical",
  "timestamp": "2026-04-15T10:23:41Z",
  "dashboard_url": "https://app.pulsewise.io/incidents/abc123"
}

Writing alert rules

Build rules in Settings → Alerts → Rules. A rule is just a metric, an operator, a threshold, a sustain duration, and the channels to notify. Scope it to one server, a group, or the whole fleet — whatever maps to how you’re on call.

AI Incident Diagnostics

When an alert fires or a server starts behaving badly, Pulsewise writes a plain-language explanation of what’s happening — before you even open the dashboard.

How it works

The engine pulls together the trigger metric, recent trends, service state changes, top processes, and any correlated activity on neighbouring servers. It cross-references your fleet’s normal baseline and writes a summary in the same language a senior SRE would use.

What’s in the summary

  • What happened — the anomaly in one sentence
  • When it started — onset time inferred from metric trends
  • What’s affected — the service, process, or resource under pressure
  • Likely root cause — the most probable trigger given the signals
  • Suggested next steps — concrete actions, not vague guidance

Availability

Included on Growth and Scale. Scale adds cross-server correlation and trend-based prediction so recurring issues get flagged before they recur.

Diagnostics use only operational metrics and system context. Pulsewise never reads your application code, environment variables, file contents, or user data.

Team & Workspace Setup

Workspaces are the boundary between teams, environments, or clients. Each one has its own servers, alert rules, incident history, and members — nothing leaks across.

Inviting teammates

Go to Settings → Team → Invite, enter an email, hit send. They’ll get a one-click join link. Available on every plan.

Roles

The Scale plan adds role-based access control:

  • Owner — full access, billing, workspace deletion
  • Admin — manage servers, alerts, and team
  • Member — view dashboard, acknowledge incidents
  • Viewer — read-only access

Server groups

Group servers by environment, app, region, or team. Use groups to scope alerts (“page only when prod-web tier is sick”), filter dashboards, and assign on-call ownership.

Billing & Account

Everything billing-related lives in Settings → Billing.

Changing your plan

Upgrade, downgrade, or cancel anytime. Upgrades apply instantly and are prorated. Downgrades take effect at the start of your next billing period — you keep what you paid for.

Payment methods

We accept Visa, Mastercard, American Express, and Discover. Payments are processed by Stripe — your card details never touch our servers.

Invoices

Issued automatically each cycle and emailed to the workspace owner. Download past invoices anytime from Settings → Billing → Invoice History.

Cancelling

Cancel from Settings → Billing → Cancel Subscription. The plan stays active until your current period ends. Data is retained for 30 days after cancellation, then permanently deleted.

Troubleshooting

Agent shows offline

Run through this checklist:

  1. Is the service running? sudo systemctl status pulsewise-agent
  2. Can the box reach us? curl -I https://api.pulsewise.io
  3. Does the token in /etc/pulsewise/config.yml match your workspace?
  4. What do the logs say? sudo journalctl -u pulsewise-agent --since '10 min ago'

Connected but no metrics

The agent reached us but a collector failed. Check the logs for the specific error. Most often it’s a permission issue (the agent needs root or CAP_DAC_READ_SEARCH) or an unsupported kernel.

Alerts aren’t firing

  • Is the rule actually enabled in Settings → Alerts → Rules?
  • Has the sustain duration been met (e.g. “over 90% for 5 minutes”)?
  • Is the destination channel configured and tested?
  • Is the alert in cooldown after a recent fire?

Agent using too much CPU/RAM

Healthy baseline is under 1% CPU and 15MB RAM. If you’re seeing more, try a longer collection interval, prune the services list, or update to the latest version — most spikes are fixed in newer releases.

FAQ

Does the agent need root?

Yes. Per-process metrics, service status, and disk I/O all require it. The agent runs as a systemd service under root.

What does the agent actually send?

System metrics (CPU, memory, disk, load, network), service health, the top-N process list (name, PID, CPU%, memory%), and Docker container metadata. Never your logs, code, env vars, file contents, or user data.

Do you support Windows?

No, and it’s not on the roadmap. Pulsewise is built around Linux operational signals.

Is there an API?

Yes — a full REST API for querying metrics, incidents, and managing resources. See the API Reference.

How do I export my data?

Incidents and metrics export to CSV from the dashboard, or programmatically via the API. Available on every plan.

What if Pulsewise goes down?

The agent buffers up to an hour of metrics locally and replays them when connectivity returns. Your servers don’t notice — the agent is a passive observer, not a control plane.