Manual Service Setup

This guide is for systems where the automatic installer cannot manage the service manager for you, such as OpenRC, runit, s6, or supervisord. Prefer the installer whenever possible; it renders and installs the same service templates referenced below.

Current Architecture

agentwatch runs as a gateway plus one or more per-user daemons:

• The gateway owns HTTPS, login/auth, the Cloudflare tunnel, session routing, and name allocation.
• Each per-user daemon owns that user's tmux sessions and registers with the gateway over loopback.

On Linux, install and supervise the gateway first. User daemons are clients of that gateway; a user daemon without a gateway is not a complete install. On macOS, the same architecture runs with one user-owned gateway and one per-user daemon.

Canonical Service Inputs

Do not hand-copy old command lines into new init files. Start from the current templates and translate their fields into your service manager's syntax:

Role	Canonical template
Gateway	service-files/agentwatch-gateway.service
Per-user daemon	service-files/agentwatch.service
macOS gateway	service-files/com.agentwatch.gateway.plist
macOS per-user daemon	service-files/com.agentwatch.plist

Keep the same role, config path, restart policy, KillMode=process or equivalent process-group behavior, logging target, and PATH environment from the templates. The gateway must be supervised separately from each per-user daemon.

Prerequisites

1. Install agentwatch files without asking the installer to create services:

./install.sh --no-service

1. Generate or verify configuration:

agentwatch --generate-config > ~/.config/agentwatch/config.yaml
agentwatch --config ~/.config/agentwatch/config.yaml --json

1. On Linux shared hosts, make sure an administrator has installed the gateway configuration under /etc/agentwatch/gateway.yaml before starting per-user daemons.

Translating to Other Init Systems

For each service manager, create two service definitions on Linux:

• A system gateway service translated from service-files/agentwatch-gateway.service.
• A per-user daemon service translated from service-files/agentwatch.service and run as the target user.

For macOS launchd, use the LaunchAgent templates instead of translating the systemd units.

OpenRC

Create separate OpenRC services for the gateway and for each user daemon. The gateway service should run at the system level and start after networking. Each per-user daemon service should run as that user and depend on the gateway being available.

runit and s6

Create one long-running service directory for the gateway and one for each per-user daemon. Keep separate log services so gateway logs and per-user daemon logs can be inspected independently.

supervisord

Create separate programs for the gateway and each per-user daemon. Configure autorestart=true, separate stdout/stderr log files, and the same environment from the canonical templates.

Cron

Cron is not recommended for current agentwatch installs because the gateway and per-user daemons need independent supervision and restart behavior. If no service manager is available, use a small process supervisor instead of cron.

Verifying the Service

Regardless of init system, verify the gateway and daemon are reachable:

# Check the HTTPS health endpoint
curl -sk https://localhost:8081/health

# Check daemon and tunnel health
agentwatch health

# Check session discovery through the gateway
agentwatch session list

Troubleshooting

Gateway or daemon does not start

1. Check that tmux is available for the per-user daemon:

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

1. Validate YAML syntax:

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

1. Compare your init definition against the matching template in service-files/. If the template changed during an update, translate the new template again instead of preserving old command lines.

Health check fails

If the health endpoint does not respond:

# Confirm the supervised processes are running
pgrep -fl agentwatch

# Check the service health summary
agentwatch health

# Check the logs used by your init system
journalctl --user -u agentwatch -n 100
journalctl -u agentwatch-gateway -n 100

For non-systemd managers, use that manager's log command or the log files you configured from the template translation.

Hooks not firing

1. Enable debug logging in config:

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

1. Check hook script permissions:

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

PATH issues

If hooks cannot 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 PATH in the service environment using the matching canonical template as the baseline.