---

name: wavecap-service description: Manage WaveCap as a macOS service. Use when the user wants to start, stop, restart the service, check service status, view service logs, or manage the launchd configuration.

WaveCap Service Management Skill

Use this skill to manage WaveCap as a macOS Launch Agent service.

Service Configuration

• Plist location: ~/Library/LaunchAgents/com.wavecap.server.plist
• Service name: com.wavecap.server
• Logs: ~/Library/Logs/wavecap-server.log and wavecap-server-error.log

Service Status

Check if the service is running:

Copylaunchctl list | grep wavecap

Output format: PID EXIT_CODE LABEL

• If PID is a number and EXIT_CODE is 0: service is running
• If PID is - and EXIT_CODE is non-zero: service exited with error

Quick status check:

Copylaunchctl list com.wavecap.server 2>/dev/null && echo "Service is loaded" || echo "Service is not loaded"

Start Service

Load and start the service:

Copylaunchctl load ~/Library/LaunchAgents/com.wavecap.server.plist

Stop Service

Unload and stop the service:

Copylaunchctl unload ~/Library/LaunchAgents/com.wavecap.server.plist

Restart Service

Stop then start:

Copylaunchctl unload ~/Library/LaunchAgents/com.wavecap.server.plist && launchctl load ~/Library/LaunchAgents/com.wavecap.server.plist

View Logs

Recent stdout (application logs):

Copytail -50 ~/Library/Logs/wavecap-server.log

Recent stderr (errors):

Copytail -50 ~/Library/Logs/wavecap-server-error.log

Follow logs in real-time:

Copytail -f ~/Library/Logs/wavecap-server.log

Check for errors:

Copygrep -i error ~/Library/Logs/wavecap-server-error.log | tail -20

Verify Server is Responding

After starting, verify the server is healthy:

Copycurl -s http://localhost:8000/api/health | jq

Expected: {"status": "ok"}

Troubleshooting

Service Won't Start

1. Check error log:

   Copycat ~/Library/Logs/wavecap-server-error.log
   

2. Verify plist syntax:

   Copyplutil -lint ~/Library/LaunchAgents/com.wavecap.server.plist
   

3. Try running manually to see errors:

   Copy/Users/thw/Projects/WaveCap/backend/.venv/bin/python -m wavecap_backend
   

Service Keeps Restarting

Check exit codes in error log. Common issues:

• Missing dependencies (ffmpeg not in PATH)
• Port 8000 already in use
• Configuration errors

Find what's using port 8000:

Copylsof -i :8000

View Plist Configuration

Copycat ~/Library/LaunchAgents/com.wavecap.server.plist

Clear Logs

Copy: > ~/Library/Logs/wavecap-server.log
: > ~/Library/Logs/wavecap-server-error.log

Service Behavior

• RunAtLoad: Starts automatically when you log in
• KeepAlive: Automatically restarts if it crashes
• WorkingDirectory: /Users/thw/Projects/WaveCap/backend

Disable Auto-Start

To stop the service from starting on login (but keep the plist):

Copylaunchctl unload -w ~/Library/LaunchAgents/com.wavecap.server.plist

To re-enable:

Copylaunchctl load -w ~/Library/LaunchAgents/com.wavecap.server.plist

Remove Service Completely

Copylaunchctl unload ~/Library/LaunchAgents/com.wavecap.server.plist
rm ~/Library/LaunchAgents/com.wavecap.server.plist

Convert to Launch Daemon (System-Wide)

To run at boot (even without user login), convert to a Launch Daemon:

Copy# Stop agent
launchctl unload ~/Library/LaunchAgents/com.wavecap.server.plist

# Move to system location
sudo mv ~/Library/LaunchAgents/com.wavecap.server.plist /Library/LaunchDaemons/

# Set permissions
sudo chown root:wheel /Library/LaunchDaemons/com.wavecap.server.plist
sudo chmod 644 /Library/LaunchDaemons/com.wavecap.server.plist

# Load daemon
sudo launchctl load /Library/LaunchDaemons/com.wavecap.server.plist

Note: The plist may need a UserName key added to run as your user instead of root.