homelab/AGENTS.md

AI Agent Instructions and Restrictions

CRITICAL SECURITY RESTRICTIONS

❌ SUDO COMMAND PROHIBITION

NEVER, UNDER ANY CIRCUMSTANCES, RUN SUDO COMMANDS

The AI agent MUST NOT execute any commands that require elevated privileges:

• ❌ sudo commands
• ❌ su commands
• ❌ Commands that modify system files directly
• ❌ Commands that require root privileges

✅ APPROVED ALTERNATIVES

Instead of running sudo commands, the AI should:

1. Create scripts that the user can run with sudo -A
2. Document commands for the user to execute manually
3. Explain what needs to be done and why
4. Provide step-by-step instructions for the user

EXAMPLES

❌ WRONG:

sudo systemctl restart nginx
sudo chmod 755 /etc/nginx/conf.d/

✅ CORRECT:

# Create a script for the user to run
echo "systemctl restart nginx" > /tmp/restart-nginx.sh
chmod +x /tmp/restart-nginx.sh

# Then tell the user:
# "Run: sudo -A /tmp/restart-nginx.sh"

RATIONALE

• User explicitly denied AI access to sudo
• Security best practice: AI should not have root privileges
• User prefers manual control over system changes
• Prevents accidental system modifications

VERIFICATION

This restriction has been tested and verified:

• ✅ AI cannot run sudo commands via bash tool
• ✅ AI will create scripts instead
• ✅ User maintains full control over privileged operations

OTHER OPERATIONAL GUIDELINES

File Operations

• ✅ Read files in user directories
• ✅ Write files in user directories
• ✅ Create scripts in /tmp or user directories
• ❌ Modify system configuration files directly

Network Operations

• ✅ Check network status with unprivileged commands
• ✅ Test connectivity
• ❌ Modify firewall rules directly
• ❌ Bind to privileged ports (< 1024)

Service Management

• ❌ Start/stop/restart system services directly
• ✅ Check service status with unprivileged commands
• ✅ Create systemd service files for user to deploy

---

REMEMBER: When in doubt, create a script and let the user run it with sudo.