Quick Start Guide

Get preheat running and verified in under 5 minutes.

Prerequisites

• Preheat is installed (see Installation)
• You have root/sudo access
• systemd is your init system

Step 1: Check Service Status

First, verify preheat is running:

sudo systemctl status preheat

Expected output (service running):

● preheat.service - Adaptive readahead daemon
     Loaded: loaded (/usr/lib/systemd/system/preheat.service; enabled)
     Active: active (running) since Mon 2024-12-15 10:00:00 UTC
   Main PID: 1234 (preheat)
     Memory: 5.2M

If not running, start it:

sudo systemctl start preheat

Or first verify system requirements:

preheat --self-test

Step 2: Verify Daemon Operation

Check the log file to confirm normal operation:

sudo tail -30 /usr/local/var/log/preheat.log

Healthy log output looks like:

[Mon Dec 15 10:00:00 2024] loading configuration from /usr/local/etc/preheat.conf
[Mon Dec 15 10:00:00 2024] loading state from /usr/local/var/lib/preheat/preheat.state
[Mon Dec 15 10:00:00 2024] preheat 1.0.1 started

After a few cycles (20 seconds each by default), you’ll see:

[Mon Dec 15 10:00:20 2024] 47 running processes, 23 tracked applications

Step 3: Use the CLI Tool

Check daemon status programmatically:

preheat-ctl status

Output:

preheat is running (PID 1234)

Dump current statistics to the log:

sudo preheat-ctl dump

Then view:

sudo tail -50 /usr/local/var/log/preheat.log

Step 4: Understand the Learning Period

Preheat needs time to learn your usage patterns:

Note: Preheat doesn’t start from scratch! On first run, it seeds its model from your XDG recently-used files, shell history, and installed browsers. You’ll see benefits immediately.

During the learning period:

• The daemon runs normally
• It monitors and records application launches
• Predictions improve automatically over time
• You don’t need to do anything special

Step 5: Verify Preloading is Working

After at least an hour of normal use, check if predictions are happening:

# Force a state dump
sudo preheat-ctl dump

# Check the log for prediction activity  
sudo grep -i "readahead\|preload\|predict" /usr/local/var/log/preheat.log | tail -20

You should see entries indicating file preloading activity.

Quick Command Reference

Default Behavior Explained

Out of the box, preheat uses safe, conservative defaults:

These defaults:

• Work well on most systems
• Prioritize safety over aggressiveness
• Require no tuning for basic operation

What to Expect

Immediate Effects

• Daemon starts and begins monitoring
• Log file shows activity
• Memory usage increases slightly (5-10 MB daemon overhead)

After Learning (Hours to Days)

• Frequently used applications start faster
• Most noticeable on HDDs
• Improvement varies by workflow predictability

Typical Results

Quick Troubleshooting

Service won’t start

# Check for errors
sudo journalctl -u preheat -n 50

# Check if something else uses the PID file
ls -la /run/preheat.pid

# Try running in foreground for debugging
sudo preheat -f

Log shows errors

# Check configuration syntax
sudo preheat --help

# Verify configuration file
cat /usr/local/etc/preheat.conf

No improvement noticed

• Give it time: Learning takes hours to days
• Check if running: sudo preheat-ctl status
• Your workflow may be unpredictable: Random app usage defeats prediction

See Troubleshooting for detailed problem resolution.

Next Steps

Now that preheat is running:

1. How It Works - Understand the daemon’s behavior
2. Configuration - Tune for your specific needs
3. Advanced Usage - Power-user optimizations

Navigation