Manual Service Setup¶

This guide covers setting up agentwatch as a service on systems not supported by the automatic installer (OpenRC, runit, s6, etc.).

Prerequisites¶

Install agentwatch files without the service:
```
./install.sh --no-service
```

Verify the installation:

# Check the binary works
~/.local/bin/agentwatch --help

# Check the config is valid
~/.local/bin/agentwatch --config ~/.config/agentwatch/config.yaml --json

Installation Paths¶

The --no-service installation creates:

File	Path
Binary (symlink)	`~/.local/bin/agentwatch`
Config	`~/.config/agentwatch/config.yaml`
Hook scripts	`~/.config/agentwatch/hooks.d/`

Running Manually¶

For testing or simple use cases, run the daemon manually:

# Foreground (for testing)
~/.local/bin/agentwatch --daemon --config ~/.config/agentwatch/config.yaml

# Background
~/.local/bin/agentwatch --daemon --config ~/.config/agentwatch/config.yaml &

# With nohup (survives logout)
nohup ~/.local/bin/agentwatch --daemon --config ~/.config/agentwatch/config.yaml > /tmp/agentwatch.log 2>&1 &

OpenRC (Alpine, Gentoo)¶

Create /etc/init.d/agentwatch:

#!/sbin/openrc-run

name="agentwatch"
description="Terminal state detection daemon"
user="YOUR_USERNAME"
command="/home/${user}/.local/bin/agentwatch"
command_args="--daemon --config /home/${user}/.config/agentwatch/config.yaml"
command_user="${user}"
command_background="yes"
pidfile="/run/${RC_SVCNAME}.pid"

depend() {
    need localmount
    after bootmisc
}

Then:

sudo chmod +x /etc/init.d/agentwatch
sudo rc-update add agentwatch default
sudo rc-service agentwatch start

runit (Void Linux, Artix)¶

Create /etc/sv/agentwatch/run:

#!/bin/sh
USER="YOUR_USERNAME"
HOME="/home/$USER"
exec chpst -u $USER \
    $HOME/.local/bin/agentwatch \
    --daemon \
    --config $HOME/.config/agentwatch/config.yaml \
    2>&1

Create /etc/sv/agentwatch/log/run:

#!/bin/sh
exec svlogd -tt /var/log/agentwatch

Then:

sudo chmod +x /etc/sv/agentwatch/run
sudo chmod +x /etc/sv/agentwatch/log/run
sudo ln -s /etc/sv/agentwatch /var/service/

s6¶

Create /etc/s6/sv/agentwatch/run:

#!/bin/execlineb -P
s6-setuidgid YOUR_USERNAME
/home/YOUR_USERNAME/.local/bin/agentwatch
--daemon
--config
/home/YOUR_USERNAME/.config/agentwatch/config.yaml

Create /etc/s6/sv/agentwatch/type:

longrun

supervisord¶

Add to /etc/supervisord.conf or /etc/supervisor/conf.d/agentwatch.conf:

[program:agentwatch]
command=/home/YOUR_USERNAME/.local/bin/agentwatch --daemon --config /home/YOUR_USERNAME/.config/agentwatch/config.yaml
user=YOUR_USERNAME
autostart=true
autorestart=true
stderr_logfile=/var/log/agentwatch.err.log
stdout_logfile=/var/log/agentwatch.out.log

Then:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start agentwatch

Cron (last resort)¶

For systems without a proper init system, use cron with a wrapper script.

Create ~/.local/bin/agentwatch-cron:

#!/bin/bash
PIDFILE="/tmp/agentwatch.pid"
LOGFILE="/tmp/agentwatch.log"

if [ -f "$PIDFILE" ] && kill -0 "$(cat "$PIDFILE")" 2>/dev/null; then
    exit 0  # Already running
fi

~/.local/bin/agentwatch \
    --daemon \
    --config ~/.config/agentwatch/config.yaml \
    >> "$LOGFILE" 2>&1 &

echo $! > "$PIDFILE"

Add to crontab (crontab -e):

@reboot ~/.local/bin/agentwatch-cron
* * * * * ~/.local/bin/agentwatch-cron

Verifying the Service¶

Regardless of init system, verify the daemon is working:

# Check the socket exists
ls -la /tmp/agentwatch.sock

# Send a ping
echo "ping" | nc -U /tmp/agentwatch.sock

# Get status of all sessions
echo "status" | nc -U /tmp/agentwatch.sock

Troubleshooting¶

Daemon doesn't start¶

Check if tmux is available:

which tmux
tmux list-sessions  # Should work even if no sessions exist

Run manually to see errors:

~/.local/bin/agentwatch --daemon --config ~/.config/agentwatch/config.yaml

Check config syntax:

python3 -c "import yaml; yaml.safe_load(open('$HOME/.config/agentwatch/config.yaml'))"

Socket permission issues¶

If you get "permission denied" on the socket:

# Check socket permissions
ls -la /tmp/agentwatch.sock

# Remove stale socket
rm /tmp/agentwatch.sock

Hooks not firing¶

Enable debug logging in config:

service:
  log_level: DEBUG
  debug:
    enabled: true
    log_hooks: true

Check hook script permissions:

ls -la ~/.config/agentwatch/hooks.d/
chmod +x ~/.config/agentwatch/hooks.d/*.sh

PATH issues¶

If hooks can't find commands, ensure PATH is set:

# In hook scripts, add:
export PATH="$HOME/.local/bin:$HOME/.npm-global/bin:/usr/local/bin:/usr/bin:/bin:$PATH"

Or set in the service environment (varies by init system).