Back
61/65
Lesson 61
7 min
ACFS Doctor & Maintenance
Keep your environment healthy with doctor checks, nightly updates, and SRPS
Ready to level up?
Mark complete to track your learning progress.
Keep your environment healthy with doctor checks, nightly updates, and SRPS
Mark complete to track your learning progress.
Keep your ACFS environment healthy with doctor checks, automated nightly updates, and workspace management — the maintenance tools that prevent environment drift.
AI agents depend on correctly installed tools. A broken PATH, missing binary, or stale config can waste hours of debugging time. ACFS includes three maintenance systems that catch problems early, before they derail your work.
Health checks for every installed component
A user timer runs acfs update while you sleep
/data/projects plus NTM sessions that survive disconnects
System resource protection under load
The acfs doctor command runs health checks on every component installed by ACFS. It checks binary existence, version constraints, and configuration validity — giving you a quick snapshot of your entire environment.
1# Run full system health check2acfs doctor34# Example output:5# ✓ zsh ........................ 5.96# ✓ oh-my-zsh ................. installed7# ✓ bun ....................... 1.2.18# ✓ uv ........................ 0.5.29# ✗ rust ...................... NOT FOUND10# ✓ go ........................ 1.23.011# ✓ tmux ...................... 3.5a12# ✓ claude-code ............... 1.0.3213# ✓ ntm ....................... 2.1.014# ...15#16# Results: 68/70 checks passed, 2 issues found1718# Auto-fix discovered issues19acfs doctor --fix2021# JSON output for programmatic use22acfs doctor --format json2324# Preview fixes without applying them25acfs doctor --fix --dry-run2627# Deeper functional checks (agent auth, service connections)28acfs doctor --deep
acfs doctor at the start of every session. It takes under 5 seconds and catches issues before they waste hours of agent time.A per-user systemd timer runs acfs update every night (around 4am). It first skips the run if the machine is overloaded or nearly out of disk, then updates your tools. ACFS's own scripts are not self-updated unless you opt in.
1# Check nightly update status (a user timer: note --user, no sudo)2systemctl --user status acfs-nightly-update.timer34# View the most recent nightly log5ls -t ~/.acfs/logs/updates/nightly-*.log | head -1 | xargs tail -n 5067# Trigger a manual update now8acfs update910# What the nightly run does:11# 1. Skips if load is too high or disk is critically low (<2GB)12# 2. Low-risk cleanup if disk is tight (<5GB)13# 3. Runs acfs-update --yes --quiet (ACFS self-update off by default)14# 4. Logs to ~/.acfs/logs/updates/1516# Disable nightly updates (not recommended)17systemctl --user disable --now acfs-nightly-update.timer1819# Re-enable20systemctl --user enable --now acfs-nightly-update.timer
ACFS sets up a project folder and tmux/NTM so your agent sessions keep running when SSH disconnects. You can SSH back in and pick up exactly where you left off.
1# Where things live after installation:2# /data/projects/ — Your projects (NTM's projects_base)3# ~/.acfs/ — ACFS scripts, state and logs4# ~/.acfs/tmux/tmux.conf — Tmux configuration5# ~/.acfs/zsh/acfs.zshrc — Shell configuration67# Create a project (in /data/projects/myproject)8acfs newproj myproject910# Start agents in a named session (session name = project folder)11ntm spawn myproject --cc=1 --cod=11213# Reconnect after SSH drops14ntm attach myproject
ntm attach myproject (or tmux attach), and immediately start working. Agent sessions persist across disconnections.The System Resource Protection Service prevents agents from overwhelming the VPS. It monitors CPU, memory, disk, and process count, taking automatic action when thresholds are exceeded.
1# Check current system resource status2srps status34# What SRPS monitors:5# - CPU usage > 90% for > 60 seconds → throttle agents6# - Memory usage > 85% → warn, > 95% → emergency cleanup7# - Disk usage > 90% → block new writes8# - Process count > 500 → kill orphaned processes910# View SRPS alerts11srps alerts --last 101213# Configure thresholds14srps config set cpu-warning 8015srps config set memory-critical 951617# When SRPS triggers:18# 1. Logs the event19# 2. Sends Agent Mail notification to all agents20# 3. Pauses lowest-priority agent work21# 4. Waits for resources to recover22# 5. Resumes work automatically
A practical maintenance routine that keeps your environment healthy with minimal effort.
Good maintenance is invisible. Five seconds of acfs doctor at session start prevents hours of debugging broken tools. Let the nightly timer handle updates so you can focus on building.