Deployment

This guide covers running jeeves-runner as a persistent system service.

Service Registration

The CLI provides platform-specific instructions:

jeeves-runner service install -c /path/to/config.json

Linux (systemd)

Create /etc/systemd/system/jeeves-runner.service:

[Unit]
Description=jeeves-runner
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/node /usr/lib/node_modules/@karmaniverous/jeeves-runner/dist/cli.js start -c /etc/jeeves-runner/config.json
Restart=always
RestartSec=5
User=jeeves
WorkingDirectory=/var/lib/jeeves-runner

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable jeeves-runner
sudo systemctl start jeeves-runner

Windows (NSSM)

nssm install JeevesRunner node.exe "C:\path\to\jeeves-runner\dist\cli.js" start -c "C:\config\jeeves-runner\config.json"
nssm set JeevesRunner AppDirectory "C:\path\to\jeeves-runner"
nssm set JeevesRunner AppStdout "C:\logs\jeeves-runner-stdout.log"
nssm set JeevesRunner AppStderr "C:\logs\jeeves-runner-stderr.log"
nssm start JeevesRunner

macOS (launchd)

Create ~/Library/LaunchAgents/com.karmaniverous.jeeves-runner.plist:





    Label
    com.karmaniverous.jeeves-runner
    ProgramArguments
    
        /usr/local/bin/node
        /usr/local/lib/node_modules/@karmaniverous/jeeves-runner/dist/cli.js
        start
        -c
        /etc/jeeves-runner/config.json
    
    RunAtLoad
    
    KeepAlive

launchctl load ~/Library/LaunchAgents/com.karmaniverous.jeeves-runner.plist

SQLite Maintenance

Database Location

Default: ./data/runner.sqlite (relative to working directory). Configure via dbPath in config.

Automatic Cleanup

Run retention: Completed run records older than runRetentionDays (default 30) are automatically pruned.
State cleanup: Expired state entries (those with a expires_at in the past) are cleaned up every stateCleanupIntervalMs (default 1 hour).

Backup

SQLite databases can be backed up while the runner is running:

sqlite3 /path/to/runner.sqlite ".backup /path/to/backup.sqlite"

Or use filesystem snapshots if available.

WAL Mode

The runner uses SQLite in WAL (Write-Ahead Logging) mode for concurrent read/write performance. The -wal and -shm files alongside the database are normal and should be included in backups.

Network Configuration

Default port is 1937. Default bind address is 0.0.0.0 (all interfaces). Change via port and host in config:

{
  "port": 3100,
  "host": "127.0.0.1"
}

Set host to 127.0.0.1 to restrict access to localhost only. Ensure firewall rules allow access if exposing the API externally.

Monitoring

Status Endpoint

curl http://localhost:1937/status

Returns { name, version, uptime, status, health: { totalJobs, running, failedRegistrations, okLastHour, errorsLastHour } }.

Use this for load balancer or uptime monitoring health checks. Monitor health.errorsLastHour and health.failedRegistrations for alerting.

Logs

Configure logging in the config file:

{
  "log": {
    "level": "info",
    "file": "/var/log/jeeves-runner.log"
  }
}

Log levels: trace, debug, info, warn, error, fatal.