# Rackpulse

> Rackpulse is a free, open source macOS menu bar app for your cloud servers. It shows your servers from all your projects, whether they are running, how busy they are, and what they cost this month. It sends a notification when something goes wrong.

- Website: https://rackpulse.app/
- Download: https://rackpulse.app/download/Rackpulse.dmg
- Source: https://github.com/en3sis/rackpulse
- Discord: https://discord.gg/s4AzG5sc36
- Version: 0.2.2
- License: MIT, open source, free
- Platform: macOS 14 or later
- Providers: Hetzner Cloud. More providers, and servers with only the agent, are in progress
- No account, no telemetry
- Not affiliated with Hetzner Online GmbH or any other provider

## Providers and agent

Rackpulse reads your cloud provider's API with a key you create, so it needs nothing on your servers. The agent is a small read-only Linux program that adds what a provider's API can't see. You can mix both: some servers with the agent, some without.

| Provider | State | Key |
|---|---|---|
| Hetzner Cloud | Supported | One API token per project (Read, or Read & Write for power actions) |
| More providers | In progress | |
| Servers with only the agent | In progress | |

## With a provider key (Simple mode)

- One status line for all projects, for example "All 5 servers running" or "1 not running · 2 alerts", in the colour of the worst alert.
- Servers grouped by project, with problems sorted to the top. Each server can be tagged Production, Staging, or Development, also read from an `env` label.
- Charts for CPU, disk IOPS, and network, from 1 hour to 30 days.
- 30 days of uptime, from the provider's start and stop history and Rackpulse's own checks.
- Power controls: start, shut down, reboot, power off, and reset, each confirmed first. Needs a key that can write.
- Costs: month to date and the forecast to month end per project, with an optional budget. Stopped servers that still bill, and volumes or IPs that nothing uses, are listed separately. The numbers are estimates from the provider's list prices and the hours each resource existed this month, capped at the monthly price. Hetzner has no billing API, so credits and extra traffic are not included. VAT is added only when you choose prices with VAT in Settings. For a server on an older Hetzner price, you can enter the monthly price you pay, and Rackpulse uses it instead of the list price. A Show cost estimates switch in Settings, General hides all cost amounts and stops budget alerts.
- Menu bar readout: the busiest server's CPU, this month's cost, or the number of alerts.
- Press ⌃⌥R from any app to open the panel, then type to find a server. The panel can be locked with Touch ID after the Mac sleeps.

## The agent (optional)

With the agent, a server page also shows:

- Memory, load, how full each disk is (space and inodes), failed systemd services, and when a reboot is needed.
- Docker containers, grouped by Compose project, with their health, restarts, CPU, and memory. Each container has its own page with ports, volumes, networks, the last health check, and 7 days of history.
- Docker disk usage: images, volumes, build cache, and container layers, and how much is reclaimable.
- 30 days of uptime recorded on the server itself, so it also catches crashes that the provider can't see.

How the agent works:

- One static binary for Linux (x86_64 and ARM64), run as a systemd service under its own `rackpulse` user.
- It listens on TCP port 7311 over HTTPS (TLS 1.3). Rackpulse on your Mac connects to it.
- It is read-only. It has no endpoint that runs a command or changes anything. Docker is read through read-only API requests, with systemd sandboxing.
- Each server has its own random 256-bit key. Rackpulse pins the agent's TLS certificate on the first connection.
- It keeps 30 days of history in `/var/lib/rackpulse-agent`.

Install: open a server in Rackpulse, choose Set up agent, and run the command it shows as root on the server:

```bash
curl -fsSL https://rackpulse.app/agent/install.sh | sudo sh -s -- --pair rb1_...
```

Then make TCP port 7311 reachable from your Mac. On a public IP, add an inbound rule to the server's cloud firewall, and if ufw is active, run `sudo ufw allow 7311/tcp`. Over Tailscale, another VPN, or a private network, no public rule is needed.

Update: run the install command again without `--pair`. It keeps the key, port, and address. Remove: `sudo rackpulse-agent uninstall`, then remove the firewall rule and choose Remove agent in Rackpulse.

## Alerts

| Rule | Fires when | Mode |
|---|---|---|
| Server down | A server is not running and you did not stop it | Simple |
| Sustained CPU | CPU stays above the threshold for the whole period | Simple |
| Traffic quota | Outgoing traffic passes a share of the included traffic | Simple |
| Disk I/O anomaly | Disk IOPS stay above a multiple of the 7-day median | Simple |
| Budget | The month's cost forecast goes above the project's budget | Simple |
| Unexpected change | A server or volume appears or disappears, a server is rebuilt, or a firewall changes | Simple |
| Disk space | A file system passes a share of its space or inodes, or turns read-only | Agent |
| Memory | Memory use stays above the threshold for the whole period | Agent |
| Docker containers | A container is unhealthy, keeps restarting, or stopped with an error | Agent |
| Failed service | A systemd service is in the failed state | Agent |
| Reboot required | Installed updates need a reboot | Agent |
| Agent not answering | The provider says the server runs, but the agent does not answer | Agent |

Each rule has its own threshold and duration. A server can use the global rules, its own thresholds, or no alerts. Snooze silences an alert for 24 hours. Quiet hours hold notifications back.

## Privacy

- Rackpulse only talks to your provider's API, its own update feed, and the agents you set up.
- API keys and agent keys are stored in the macOS Keychain, never in a file.
- With a read-only key, Rackpulse can't change anything in your projects.
- Each agent has its own key. Without that key, nobody can read the agent's data.
- The app runs in the macOS App Sandbox and is signed and notarized by Apple.

## Install

1. Download Rackpulse.dmg, open it, and drag Rackpulse to Applications.
2. Create an API key at your provider. For Hetzner Cloud: in the Hetzner Console, open a project, go to Security, then API tokens, and create a token. Choose Read, or Read & Write to start and stop servers from Rackpulse.
3. Click the Rackpulse icon in the menu bar, paste the key, and click Verify and Save. Add one key for each project.

Rackpulse checks for updates once a day and asks before it installs one.

## FAQ

- Which providers are supported? Hetzner Cloud today. More providers, and servers with only the agent, are in progress.
- Do I need to install anything on my servers? No. The agent is optional.
- Which key permission should I choose? Read-only to monitor. A key that can write for the power actions.
- How accurate are the costs? Estimates from list prices. No VAT unless chosen in Settings, no credits, no extra traffic.
- Does the agent need a public port? Port 7311 must be reachable from your Mac. Over Tailscale, a VPN, or a private network, no public rule is needed.
- Does monitoring stop when the Mac sleeps? Rackpulse checks while the Mac is awake. The agent records 30 days of history on the server, so charts and uptime fill in later.
- Is it free? Yes, MIT License.