RAM Sentinel 🛡️

The Surgical Memory Guardian for Linux Desktops.

Your Linux froze because you opened too many tabs?

RAM Sentinel prevents that by killing only the offending processes (like Chrome renderer tabs) before your system locks up.

Stop nuking my entire browser when I'm opening too many tabs!

No more:

• losing your entire browser session
• 30-second freezes before OOM kicks in
• random process deaths you didn’t anticipate

ram-sentinel runs as a normal user (no root required) and keeps you informed via desktop notifications.

Unlike tools like earlyoom or nohang, it doesn’t kill your biggest app.
It uses Surgical Process Targeting to remove only low-value processes (like individual browser tabs).

So when memory runs low:

• You get a warning before things go bad
• The right processes get killed first
• Your main apps stay alive

🚀 What happens under memory pressure?

Without RAM Sentinel:

• System starts stuttering
• Everything freeze for ~30 seconds
• The OOM killer nukes your entire browser
• You lose all tabs and unsaved work

With RAM Sentinel:

• You get an early warning
• Only the expendables (e.g. individual Chrome tabs) are removed
• Your browser stays alive
• Your system stays responsive

Step 1: The Warning

You get an early warning that your system is under pressure, but still responsive.

Step 2: The Kill

It starts removing pressure: killing processes marked as expendable (like heavy tabs).

Step 3: Peace Restored

Pressure relieved. Your system stays smooth: no freeze, no mass process death, no surprises.

👉 This is the difference between: reacting after your system is already unresponsive vs acting before things go bad.

⚡ Quick Start

You don't have to configure anything to get started. ram-sentinel ships with Sane Defaults that work for most desktop users.

Installation

Using Cargo

cargo install ram-sentinel

Binary download

curl -L https://github.com/benedictjohannes/ram-sentinel/releases/latest/download/ram-sentinel-linux-amd64 -o ram-sentinel && \
chmod +x ram-sentinel && \
sudo mv ram-sentinel /usr/local/bin/

Run immediately

ram-sentinel

Enable as a Service (Recommended)

Generate a systemd unit and enable it:

# Preview the unit file 
ram-sentinel --print-systemd-user-unit

# Install and Enable
mkdir -p ~/.config/systemd/user/
ram-sentinel --print-systemd-user-unit ~/.config/systemd/user/ram-sentinel.service
# edit if necessary
systemctl --user daemon-reload
systemctl --user enable --now ram-sentinel

⚙️ Configuration

ram-sentinel looks for a config file in $XDG_CONFIG_HOME/ram-sentinel.toml (usually ~/.config/ram-sentinel.toml).

🌟 Recommended Configuration

For the best "Anti-Freeze" experience, start with the provided config.example.toml. It includes pre-tuned settings for:

• Surgical Targeting: Kills browser renderers and dev tools before touching your IDE.
• PSI (Pressure Stall Information): Acts when the system starts stuttering, preventing hard lockups.
• Ignore List: Protects your desktop environment and essential background services.

To use it:

curl -L https://raw.githubusercontent.com/benedictjohannes/ram-sentinel/master/config.example.toml -o ~/.config/ram-sentinel.toml
# edit to your liking

Sane Defaults 🛡️

If no config file is found, ram-sentinel loads this configuration automatically.

[ram]
warn_min_free_percent = 10.0
kill_min_free_percent = 5.0

[psi]
# PSI disabled by default to be safe

check_interval_ms = 1000
warn_reset_ms = 30000
sigterm_wait_ms = 5000
kill_targets = [
  "type=renderer",
  "-contentproc"
]
allow_kill_outside_targets = false
ignore_targets = ["ram-sentinel"]
kill_strategy = "highest_oom_score"

🔍 Validating your Configuration

You can verify your configuration file using the --check-config flag. This will load the config, validate all values and regex patterns, and print the effective configuration that ram-sentinel will use.

# Check your default config
ram-sentinel --check-config

# Check a specific config file
ram-sentinel --config my-test-config.toml --check-config

🧠 Design Philosophy

ram-sentinel is built on the Safety First doctrine.

1. Priority Queues: We define a priority system for processes. kill_targets are "Second Class Citizens" that gets sacrificed first. Processes in ignore_targets would never be targetted. Other apps are only touched if shedding the expendables didn't solve the memory crisis.
2. Identity Verification: Before sending the final SIGKILL, the sentinel verifies that the PID's create_time matches the victim it selected 3 seconds ago. This prevents the "PID Reuse" race condition where a guardian accidentally kills a brand new process that grabbed the dead victim's PID.
3. Strict Override: Configuration follows a "Manual Override" logic. If you set a specific Byte limit (500MB), the vague Percentage limit (5%) is ignored. You get exactly what you ask for.

ram-sentinel is heavily inspired by the excellent earlyoom and the modern systemd-oomd, implementing many features I wished they had (like surgical dual-layer targeting and fine grained userspace notification). For a deeper dive into the architectural decisions, see GEMINI.md.

🚧 Roadmap

The project is in an exciting early stage. I've used ram-sentinel on my CachyOS KDE desktop myself and it's been solid. But expect refinements and breaking (configuration) changes before 1.0.

Feedback, issues, and PRs are very welcome! Contributors wanted. 👋

1. Comprehensive Integration Testing Framework

This project deliberately skipped traditional unit tests: mocking the wild west of /proc, PSI, and real-world process chaos just breeds false confidence.

Instead, the project aims to build a full end-to-end behavioral testing suite:

• Runs the exact release binaries in a clean, reproducible environment (e.g., a minimal Ubuntu VM via virsh with 2 CPUs / 4GB RAM—the perfect choke point).
• Includes a coordinator to orchestrate scenarios and a troublemaker to simulate realistic culprits (sleeping renderer tabs, RAM-hungry spikes, mixed workloads).
• Parses structured logs, monitors live PSI/meminfo, and asserts surgical precision: "Did it snipe only the lazy tabs without touching the IDE?"

This gives us rock-solid, real-world proof that ram-sentinel delivers on its promises—no hype, just results. Conceptual details in TestingFramework.md.

2. Full System-Level Daemon Mode

Once the testing framework is battle-hardened, we'll expand beyond userspace:

• Root Mode: Optional system service for managing all system processes.
• Notification Proxy: Helper functionality to push notifications from the root daemon to user sessions.

The goal? Make ram-sentinel the go-to guardian for all things Linux: desktops, workstations, and servers. Okay, well, maybe not Android 😖