kinenix-worker

The unattended robot worker daemon and edge execution engine for Kinenix, an open-source, local AI-native RPA framework in Python.

Install from PyPI

pip install "kinenix[worker]"
kinenix install-browsers          # Playwright Chromium, needed for web actions
kinenix-worker info

Requires Python 3.10 or newer. To report to a Kinenix Hub, run kinenix connect http://<hub-ip>:8080 (section 3D). The Raspberry Pi quickstart below installs from the repository instead and also sets up a systemd service.

1. Overview

kinenix-worker is designed to run unattended automation workloads on edge hardware, dedicated worker machines, virtual machines, and low-power devices such as Raspberry Pi 4 Model B.

Key Capabilities

• Lightweight Execution: Minimal overhead with direct integration into kinenix-core.
• Sandbox Workspace Isolation: Executes project bundles inside disposable, per-job sandbox environments.
• Hardware Telemetry: Gathers CPU, memory, architecture, and platform metrics at runtime.
• Structured JSON Auditing: Stores hierarchical execution traces and error telemetry locally.

2. Raspberry Pi 4 Model B (ARM64) Quickstart

Prerequisites

• Hardware: Raspberry Pi 4 Model B (Rev 1.4 or compatible) with 2GB, 4GB, or 8GB RAM.
• Operating System: Raspberry Pi OS (64-bit Debian bookworm / bullseye) or Ubuntu Server ARM64.
• Network: Internet access for initial setup and downloading benchmark web pages.

Automated Setup

Clone the repository and run the setup script:

# 1. Clone repository onto Raspberry Pi
git clone -b dev https://github.com/arttopix/kinenix.git kinenix
cd kinenix

# 2. Run the setup script (it is already executable; do not chmod it, or git pull will see a local change)
./kinenix-worker/scripts/setup_rpi.sh

The script automatically:

1. Installs required Linux shared libraries for Chromium on aarch64.
2. Creates a Python 3.10+ virtual environment (.venv).
3. Installs kinenix-core and kinenix-worker in editable mode.
4. Installs the ARM64 Playwright Chromium browser.
5. Verifies the installation with kinenix-worker info.
6. Installs and starts the kinenix-worker systemd service (see section 3E). Pass --no-service to skip it.

3. Running Workflows on Raspberry Pi

A. Activate Environment

source .venv/bin/activate

B. Verify System Information

kinenix-worker info

Expected output on Raspberry Pi 4:

Kinenix Worker System Information:
-------------------------------
  os: Linux
  os_release: 6.6.x+rpt-rpi-v8
  machine: aarch64
  processor: aarch64
  python_version: 3.11.x
  cpu_count: 4
  memory_total_mb: 3884.2
  memory_available_mb: 3200.1
  memory_used_percent: 17.6
  worker_id: raspberrypi
  hub_url: (not set)
  hub_api_key: (not set)

C. Run RPA Challenge Example Flow

kinenix-worker run flows/examples/rpachallenge

To run inside an isolated sandbox directory:

kinenix-worker run flows/examples/rpachallenge --sandbox

D. Connect to the Hub

Connect once; the command asks for the Hub's worker key (on the Hub: kinenix hub show-key), checks that the Hub accepts it, and saves both in ~/.kinenix/kinenix.env, which the worker and kinenix run read:

kinenix connect http://192.168.1.132:8080
kinenix connect                 # the Hub in use and whether it answers
kinenix connect --off           # stop reporting

Environment variables still work and take precedence over the saved setting (see the Hub guide for the server side):

export KINENIX_HUB_URL=http://192.168.1.132:8080
export KINENIX_HUB_API_KEY="<key>"
export KINENIX_WORKER_ID=rpi4-01

kinenix-worker ping          # checks reachability and the API key; exit code 1 on failure
kinenix-worker run flows/examples/rpachallenge

With the URL set:

• Every run sends its execution log to the Hub. --log-dir is not needed; it only controls whether a local log file is also written.
• Every run reports the worker as busy while the flow runs and online when it finishes.
• Every command that runs flows (run, watch, schedule, daemon) also sends a heartbeat every KINENIX_HEARTBEAT_INTERVAL seconds, including during long flows. The dashboard shows the worker as offline when heartbeats stop.
• If the Hub is unreachable, flows still run. The worker logs one warning, then logs again when the connection recovers.

E. Run as a systemd Service

The service keeps kinenix-worker daemon running in the background, starts it at boot, and restarts it within 10 seconds if it stops. It runs as the user who installed it, from the repository directory, so relative flow paths such as flows/examples/rpachallenge work. While it runs, the worker sends heartbeats and shows as online in the Hub.

setup_rpi.sh installs it. To install or update it on an existing setup, run as your normal user (not root):

./kinenix-worker/scripts/install_service.sh

It reads two files in ~/.kinenix/, creating them if they do not exist (existing files are never overwritten):

Your own flows belong in your flows folder, ~/kinenix-flows, not in this repository (see Where your flows live). Keep them in a private git repository and clone it on the Pi:

git clone git@github.com:<you>/kinenix-flows.git ~/kinenix-flows     # your private repository
cd ~/kinenix-flows && git pull                                        # later, to update the flows

A trigger can then name a flow by its folder name; the worker looks it up in the flows folder (or in KINENIX_FLOWS_DIR). Paths still work too, relative to this repository.

Example triggers.json:

{
  "triggers": [
    { "type": "scheduler", "flow": "get_stock_data", "cron": "0 8 * * 1-5" },
    { "type": "scheduler", "flow": "flows/examples/bot_fx_rate", "cron": "0 8 1 * *" },
    { "type": "file_watcher", "flow": "invoice_check", "watch_dir": "/home/pi/inbox", "pattern": "*.xlsx" }
  ]
}

A scheduler runs either every interval_seconds or, when cron is set, at the minutes matching a five-field cron expression in the Pi's local time (minute hour day-of-month month day-of-week, Sunday is 0 or 7):

An invalid expression stops the daemon at startup with the field that is wrong. Check the Pi's time zone with timedatectl (set it with sudo timedatectl set-timezone Asia/Bangkok).

Jobs sent from the Hub are not supported yet; each worker runs the triggers in its own triggers.json.

4. CLI Reference

usage: kinenix-worker [-h] [--version] {info,ping,run,watch,schedule,daemon} ...

positional arguments:
    info      Display worker machine hardware, architecture, and runtime stats
    ping      Check the connection and API key to the Hub (KINENIX_HUB_URL)
    run       Execute a flow or project bundle on this worker
    watch     Watch a directory and automatically trigger a flow when new files appear
    schedule  Execute a flow on an interval (--interval) or a cron expression (--cron "0 8 1 * *")
    daemon    Run multi-trigger daemon using a configuration file

options:
  --version, -v

kinenix-worker run Options

• flow_path: Flow name, project bundle directory, or path to a flow.md.
• --sandbox: Execute inside an isolated temporary sandbox (~/.kinenix/workspaces/<job_id>).
• --vars: JSON string of variables to override.
• --log-dir: Also write a local JSON execution log to this directory. Telemetry to the Hub does not depend on it.