This guide covers the complete installation, setup, and configuration of the family MacBook monitoring system.
Your homelab must have these services running:
seq.speicher.family:12201beszel.speicher.familygrafana.speicher.family
## Create homelab directory
mkdir -p ~/homelab
cd ~/homelab
## Clone the family MacBook repository
git clone https://github.com/dratspiker/family-macbook.git
cd family-macbook
## Install Homebrew if needed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
## Install required packages
brew install \
osquery \
beszel \
fswatch \
jq \
yq \
gnu-sed
## Install Python dependencies
pip3 install pyyaml requests
## Enable SSH access
sudo systemsetup -setremotelogin on
## Configure firewall for monitoring
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /usr/local/bin/beszel-agent
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /usr/local/bin/osqueryd
## Enable FileVault encryption
sudo fdesetup enable
## Configure automatic updates
sudo defaults write /Library/Preferences/com.apple.SoftwareUpdate AutomaticCheckEnabled -bool true
sudo defaults write /Library/Preferences/com.apple.SoftwareUpdate AutomaticDownload -bool true
https://beszel.speicher.family
## Create configuration directory
mkdir -p ~/.homelab/config
## Create Beszel configuration
cat > ~/.homelab/config/beszel-key.conf << 'EOF'
export BESZEL_AGENT_KEY="your-agent-key-here"
export BESZEL_SERVER="beszel.speicher.family"
export BESZEL_PORT="45876"
EOF
## Secure the configuration
chmod 600 ~/.homelab/config/beszel-key.conf
## Create system daemon
sudo cp config/launchdaemons/com.homelab.beszel-agent.plist /Library/LaunchDaemons/
sudo launchctl load /Library/LaunchDaemons/com.homelab.beszel-agent.plist
## Verify agent is running
launchctl list | grep beszel
## Copy osquery configuration
sudo cp config/osquery/osquery.conf /var/osquery/
sudo cp config/osquery/osquery.flags /var/osquery/
## Set proper permissions
sudo chown root:wheel /var/osquery/osquery.*
sudo chmod 644 /var/osquery/osquery.*
## Load osquery daemon
sudo osqueryctl start
## Verify osquery is running
sudo osqueryctl status
## Create log forwarding configuration
cat > ~/.homelab/config/seq-forwarder.conf << 'EOF'
SEQ_SERVER="seq.speicher.family"
SEQ_PORT="12201"
SEQ_API_KEY="your-seq-api-key"
LOG_LEVEL="INFO"
EOF
## Deploy log forwarder
sudo cp scripts/seq-forwarder.sh /usr/local/bin/
sudo chmod +x /usr/local/bin/seq-forwarder.sh
## Install LaunchDaemon
sudo cp config/launchdaemons/com.homelab.seq-forwarder.plist /Library/LaunchDaemons/
sudo launchctl load /Library/LaunchDaemons/com.homelab.seq-forwarder.plist
Edit config/family-safety.yml:
content_filtering:
enabled: true
## DNS-based filtering (network level)
dns_filtering:
provider: "cloudflare-family" # or "quad9", "cleanbrowsing"
custom_blocklist:
- "adult-content.example.com"
- "gambling-site.example.com"
## Category blocking
blocked_categories:
- adult_content
- gambling
- violence
- drugs_alcohol
## Safe search enforcement
safe_search:
google: enforce
bing: enforce
youtube: moderate
duckduckgo: enforce
Configure time limits and schedules:
screen_time:
## Daily limits
daily_limits:
weekday: 4h
weekend: 6h
## Scheduled downtime
downtime:
school_nights:
start: "21:00"
end: "07:00"
days: ["sun", "mon", "tue", "wed", "thu"]
weekend_nights:
start: "22:00"
end: "08:00"
days: ["fri", "sat"]
## App-specific limits
app_limits:
games:
daily: 1h
blocked_during: ["school_hours", "homework_time"]
social_media:
daily: 2h
blocked_during: ["school_hours", "bedtime"]
educational:
unlimited: true
Define monitored applications:
application_monitoring:
## Tracked applications
monitored_apps:
browsers:
- Safari
- "Google Chrome"
- Firefox
communication:
- Messages
- Discord
- Zoom
games:
- Roblox
- Minecraft
- Steam
social_media:
- TikTok
- Instagram
- Snapchat
## Monitoring intervals (battery optimization)
check_intervals:
active_window: 30s # Current app
background_apps: 5m # All running apps
browser_history: 30m # Web activity
Set up notifications and alerts:
alerts:
## Immediate notifications
critical_alerts:
- inappropriate_content_attempt
- vpn_connection_detected
- blocked_app_bypass_attempt
- excessive_failed_login_attempts
## Daily summaries
daily_reports:
enabled: true
time: "20:00"
recipients:
- "parents@speicher.family"
## Integration with homelab
webhook_notifications:
enabled: true
n8n_webhook: "https://n8n.speicher.family/webhook/family-alerts"
## Generate new SSH key pair
ssh-keygen -t ed25519 -f ~/.ssh/family-macbook-homelab -C "family-macbook@speicher.family"
## Add to SSH agent
ssh-add ~/.ssh/family-macbook-homelab
## Use the provided script
./scripts/save-ssh-key-to-1password.sh
## Or manually save:
## 1. Open 1Password
## 2. Create new SSH Key item
## 3. Title: "Family MacBook Homelab SSH Key"
## 4. Copy private and public keys
## Copy public key to servers
for server in lucille4 lucille5 nas02 loose-seal; do
ssh-copy-id -i ~/.ssh/family-macbook-homelab.pub $server
done
Run the all-in-one setup script:
## Make script executable
chmod +x scripts/complete-setup.sh
## Run with sudo (required for system services)
sudo ./scripts/complete-setup.sh
## Follow the interactive prompts
The script will:
## Run comprehensive health check
./scripts/health-check.sh
## Check individual services
launchctl list | grep homelab
sudo osqueryctl status
pgrep -f beszel-agent
## Test Beszel connection
curl -k https://beszel.speicher.family/api/health
## Test Seq logging
echo "Test log from family MacBook" | nc -u seq.speicher.family 12201
## Check Tailscale
tailscale status
https://grafana.speicher.family
## Check LaunchDaemon errors
sudo launchctl print system/com.homelab.beszel-agent
tail -f /var/log/system.log | grep homelab
## Reset services
sudo launchctl unload /Library/LaunchDaemons/com.homelab.*.plist
sudo launchctl load /Library/LaunchDaemons/com.homelab.*.plist
## Verify network connectivity
ping beszel.speicher.family
nc -zv seq.speicher.family 12201
## Check agent logs
tail -f ~/.homelab/logs/beszel-agent.log
tail -f /var/log/osquery/osqueryd.results.log
## Optimize monitoring intervals
./scripts/optimize-battery.sh
## Check resource usage
top -o cpu | grep -E "beszel|osquery"
~/homelab/family-macbook/
├── config/
│ ├── family-safety.yml # Main safety configuration
│ ├── monitoring.yml # Monitoring intervals
│ ├── osquery/ # osquery configs
│ └── launchdaemons/ # System services
├── scripts/
│ ├── complete-setup.sh # Full setup script
│ ├── health-check.sh # Service verification
│ └── optimize-battery.sh # Battery optimization
└── logs/ # Application logs
~/.homelab/config/beszel-key.conf - Beszel agent credentials~/.homelab/config/seq-forwarder.conf - Seq logging config/var/osquery/osquery.conf - osquery configuration/Library/LaunchDaemons/com.homelab.* - System servicesconfig/family-safety.ymlFor daily operations, see the Operations Guide.