Getting Started

This guide walks you through installing and configuring jeeves-runner from scratch.

Prerequisites

• Node.js 20+ (Node.js 24+ recommended)
• SQLite support is built-in via Node.js node:sqlite

Installation

Install globally via npm:

npm install -g @karmaniverous/jeeves-runner
Copy

Or add to a project:

npm install --save-dev @karmaniverous/jeeves-runner
Copy

Initialize Configuration

Generate a starter config file:

jeeves-runner init
Copy

This creates a config.json in the default platform config directory (jeeves-runner/config.json). See the Configuration Guide for full reference.

Add Your First Job

jeeves-runner add-job \
  -c ./jeeves-runner/config.json \
  --id hello-world \
  --name "Hello World" \
  --schedule "*/5 * * * *" \
  --script /path/to/hello.js
Copy

This registers a job that runs every 5 minutes. The script must be an absolute path to an executable script.

Job Types

Type	Description
script	Spawns a child process to run the script (default)
session	Dispatches the script content to an OpenClaw Gateway session

Start the Runner

jeeves-runner start -c ./jeeves-runner/config.json
Copy

The runner starts:

1. SQLite database initialization and migrations
2. Job schedule registration via cron
3. HTTP API server on the configured port (default: 1937)

Verify

Check the runner is healthy:

curl http://localhost:1937/status
Copy

{
  "name": "runner",
  "version": "0.8.0",
  "uptime": 12.345,
  "status": "ok",
  "health": {
    "totalJobs": 1,
    "running": 0,
    "failedRegistrations": 0,
    "okLastHour": 0,
    "errorsLastHour": 0
  }
}
Copy

List registered jobs:

curl http://localhost:1937/jobs
Copy

Or via the CLI:

jeeves-runner list-jobs -c ./jeeves-runner/config.json
Copy

Next Steps

• Configuration Reference � full config schema documentation
• API Reference � HTTP API endpoints
• CLI Reference � all CLI commands
• Architecture � how jeeves-runner works internally
• Deployment � running as a system service