kinenix-worker 0.2.0b1__tar.gz

kinenix_worker-0.2.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 arttopix / Kinenix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kinenix_worker-0.2.0b1/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: kinenix-worker
+Version: 0.2.0b1
+Summary: Kinenix Worker: runs Kinenix flows unattended on schedules, cron, or file triggers, and reports to the Kinenix Hub
+Author: arttopix
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/arttopix/Kinenix
+Project-URL: Documentation, https://github.com/arttopix/Kinenix/blob/main/kinenix-worker/README.md
+Project-URL: Issues, https://github.com/arttopix/Kinenix/issues
+Keywords: rpa,automation,raspberry-pi,scheduler,worker
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: kinenix>=0.2.0b1
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Dynamic: license-file
+
+# kinenix-worker
+
+The unattended robot worker daemon and edge execution engine for **[Kinenix](https://github.com/arttopix/Kinenix)**, an open-source, local AI-native RPA framework in Python.
+
+## Install from PyPI
+
+```bash
+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, set `KINENIX_HUB_URL` and `KINENIX_HUB_API_KEY` (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:
+
+```bash
+# 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](#e-run-as-a-systemd-service)). Pass `--no-service` to skip it.
+
+---
+
+## 3. Running Workflows on Raspberry Pi
+
+### A. Activate Environment
+```bash
+source .venv/bin/activate
+```
+
+### B. Verify System Information
+```bash
+kinenix-worker info
+```
+
+Expected output on Raspberry Pi 4:
+```text
+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
+```bash
+kinenix-worker run flows/examples/rpachallenge/flow.json
+```
+
+To run inside an isolated sandbox directory:
+```bash
+kinenix-worker run flows/examples/rpachallenge/flow.json --sandbox
+```
+
+### D. Connect to the Hub
+
+The worker reports to a Kinenix Hub when these environment variables are set (see the [Hub guide](https://github.com/arttopix/Kinenix/blob/main/docs/hub.md) for the server side):
+
+| Variable | Default | Purpose |
+| :--- | :--- | :--- |
+| `KINENIX_HUB_URL` | *(unset: no reporting)* | Hub base URL, for example `http://192.168.1.132:8080` |
+| `KINENIX_HUB_API_KEY` | *(unset)* | The Hub's worker key; the same variable holds the same value on the Hub |
+| `KINENIX_WORKER_ID` | host name | Name shown on the dashboard and attached to every execution |
+| `KINENIX_HEARTBEAT_INTERVAL` | `30` | Seconds between heartbeats while a worker command runs |
+
+```bash
+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):
+
+```bash
+./kinenix-worker/scripts/install_service.sh
+```
+
+It reads two files in `~/.kinenix/`, creating them if they do not exist (existing files are never overwritten):
+
+| File | Contents |
+| :--- | :--- |
+| `worker.env` | `KINENIX_HUB_URL`, `KINENIX_HUB_API_KEY`, `KINENIX_WORKER_ID` as `export` lines; owner-readable only. Also put the secrets your flows read here, for example `GMAIL_USER` and `GMAIL_APP_PASSWORD` for `email.send`: the service does not see variables set in your shell. Add `source ~/.kinenix/worker.env` to `~/.bashrc` to use the same values in your shell. |
+| `triggers.json` | Triggers for the daemon. The default `{"triggers": []}` runs no flows and only sends heartbeats. |
+
+**Your own flows** belong in your flows folder, `~/kinenix-flows`, not in this repository (see [Where your flows live](https://github.com/arttopix/Kinenix/blob/main/docs/quickstart.md#2-where-your-flows-live)). Keep them in a private git repository and clone it on the Pi:
+
+```bash
+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`:
+
+```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):
+
+| `cron` | Runs |
+| :--- | :--- |
+| `0 8 1 * *` | 08:00 on the 1st of every month |
+| `30 7 * * 1-5` | 07:30 Monday to Friday |
+| `*/15 * * * *` | Every 15 minutes |
+| `0 9 1,15 * *` | 09:00 on the 1st and 15th |
+
+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`).
+
+| Task | Command |
+| :--- | :--- |
+| Apply changes to `worker.env` or `triggers.json` | `sudo systemctl restart kinenix-worker` |
+| Status | `systemctl status kinenix-worker` |
+| Follow logs | `journalctl -u kinenix-worker -f` |
+| Stop until next boot | `sudo systemctl stop kinenix-worker` |
+| Remove the service | `./kinenix-worker/scripts/install_service.sh --uninstall` |
+
+Jobs sent from the Hub are not supported yet; each worker runs the triggers in its own `triggers.json`.
+
+---
+
+## 4. CLI Reference
+
+```text
+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`: Path to `flow.json` or project bundle directory.
+- `--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.

kinenix_worker-0.2.0b1/README.md

@@ -0,0 +1,207 @@
+# kinenix-worker
+
+The unattended robot worker daemon and edge execution engine for **[Kinenix](https://github.com/arttopix/Kinenix)**, an open-source, local AI-native RPA framework in Python.
+
+## Install from PyPI
+
+```bash
+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, set `KINENIX_HUB_URL` and `KINENIX_HUB_API_KEY` (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:
+
+```bash
+# 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](#e-run-as-a-systemd-service)). Pass `--no-service` to skip it.
+
+---
+
+## 3. Running Workflows on Raspberry Pi
+
+### A. Activate Environment
+```bash
+source .venv/bin/activate
+```
+
+### B. Verify System Information
+```bash
+kinenix-worker info
+```
+
+Expected output on Raspberry Pi 4:
+```text
+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
+```bash
+kinenix-worker run flows/examples/rpachallenge/flow.json
+```
+
+To run inside an isolated sandbox directory:
+```bash
+kinenix-worker run flows/examples/rpachallenge/flow.json --sandbox
+```
+
+### D. Connect to the Hub
+
+The worker reports to a Kinenix Hub when these environment variables are set (see the [Hub guide](https://github.com/arttopix/Kinenix/blob/main/docs/hub.md) for the server side):
+
+| Variable | Default | Purpose |
+| :--- | :--- | :--- |
+| `KINENIX_HUB_URL` | *(unset: no reporting)* | Hub base URL, for example `http://192.168.1.132:8080` |
+| `KINENIX_HUB_API_KEY` | *(unset)* | The Hub's worker key; the same variable holds the same value on the Hub |
+| `KINENIX_WORKER_ID` | host name | Name shown on the dashboard and attached to every execution |
+| `KINENIX_HEARTBEAT_INTERVAL` | `30` | Seconds between heartbeats while a worker command runs |
+
+```bash
+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):
+
+```bash
+./kinenix-worker/scripts/install_service.sh
+```
+
+It reads two files in `~/.kinenix/`, creating them if they do not exist (existing files are never overwritten):
+
+| File | Contents |
+| :--- | :--- |
+| `worker.env` | `KINENIX_HUB_URL`, `KINENIX_HUB_API_KEY`, `KINENIX_WORKER_ID` as `export` lines; owner-readable only. Also put the secrets your flows read here, for example `GMAIL_USER` and `GMAIL_APP_PASSWORD` for `email.send`: the service does not see variables set in your shell. Add `source ~/.kinenix/worker.env` to `~/.bashrc` to use the same values in your shell. |
+| `triggers.json` | Triggers for the daemon. The default `{"triggers": []}` runs no flows and only sends heartbeats. |
+
+**Your own flows** belong in your flows folder, `~/kinenix-flows`, not in this repository (see [Where your flows live](https://github.com/arttopix/Kinenix/blob/main/docs/quickstart.md#2-where-your-flows-live)). Keep them in a private git repository and clone it on the Pi:
+
+```bash
+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`:
+
+```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):
+
+| `cron` | Runs |
+| :--- | :--- |
+| `0 8 1 * *` | 08:00 on the 1st of every month |
+| `30 7 * * 1-5` | 07:30 Monday to Friday |
+| `*/15 * * * *` | Every 15 minutes |
+| `0 9 1,15 * *` | 09:00 on the 1st and 15th |
+
+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`).
+
+| Task | Command |
+| :--- | :--- |
+| Apply changes to `worker.env` or `triggers.json` | `sudo systemctl restart kinenix-worker` |
+| Status | `systemctl status kinenix-worker` |
+| Follow logs | `journalctl -u kinenix-worker -f` |
+| Stop until next boot | `sudo systemctl stop kinenix-worker` |
+| Remove the service | `./kinenix-worker/scripts/install_service.sh --uninstall` |
+
+Jobs sent from the Hub are not supported yet; each worker runs the triggers in its own `triggers.json`.
+
+---
+
+## 4. CLI Reference
+
+```text
+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`: Path to `flow.json` or project bundle directory.
+- `--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.

kinenix_worker-0.2.0b1/kinenix_worker/__init__.py

@@ -0,0 +1,5 @@
+"""
+Kinenix Worker: Unattended Robot Daemon and Edge Execution Engine.
+"""
+
+__version__ = "0.2.0b1"

kinenix_worker-0.2.0b1/kinenix_worker/cli.py

@@ -0,0 +1,186 @@
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from rich.console import Console
+
+from . import __version__, display
+from .hub_client import HeartbeatThread, HubClient
+from .runner import WorkerRunner
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="kinenix-worker",
+        description="Kinenix Worker: Unattended Robot Daemon and Edge Execution Engine"
+    )
+    parser.add_argument(
+        "--version", "-v",
+        action="version",
+        version=f"kinenix-worker {__version__}"
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Available subcommands")
+
+    # Command: info
+    subparsers.add_parser("info", help="Display worker machine hardware, architecture, and runtime stats")
+
+    # Command: ping
+    subparsers.add_parser("ping", help="Check the connection and API key to the Hub (KINENIX_HUB_URL)")
+
+    # Command: run
+    run_parser = subparsers.add_parser("run", help="Execute a flow or project bundle on this worker")
+    run_parser.add_argument("flow_path", help="Path to flow.json or project bundle directory")
+    run_parser.add_argument("--sandbox", action="store_true", help="Execute inside an isolated temporary sandbox workspace")
+    run_parser.add_argument("--vars", type=str, help="JSON string of variables to inject (e.g. '{\"env\":\"prod\"}')")
+    run_parser.add_argument("--log-dir", type=str, help="Custom directory path to store execution logs")
+
+    # Command: watch
+    watch_parser = subparsers.add_parser("watch", help="Watch a directory and automatically trigger a flow when new files appear")
+    watch_parser.add_argument("directory", help="Directory path to watch")
+    watch_parser.add_argument("--flow", required=True, help="Path to flow.json or bundle to execute")
+    watch_parser.add_argument("--pattern", default="*.*", help="File matching pattern (e.g. '*.xlsx', '*.csv')")
+    watch_parser.add_argument("--interval", type=float, default=2.0, help="Polling interval in seconds")
+    watch_parser.add_argument("--sandbox", action="store_true", help="Execute in isolated sandbox workspace")
+    watch_parser.add_argument("--vars", type=str, help="JSON string of variables to inject")
+
+    # Command: schedule
+    sched_parser = subparsers.add_parser("schedule", help="Execute a flow on a scheduled time interval")
+    sched_parser.add_argument("--flow", required=True, help="Path to flow.json or bundle to execute")
+    sched_parser.add_argument("--interval", type=float, default=60.0, help="Interval in seconds between runs")
+    sched_parser.add_argument("--cron", type=str, default=None,
+                              help="Five-field cron expression in local time, e.g. '0 8 1 * *' (overrides --interval)")
+    sched_parser.add_argument("--sandbox", action="store_true", help="Execute in isolated sandbox workspace")
+    sched_parser.add_argument("--vars", type=str, help="JSON string of variables to inject")
+
+    # Command: daemon
+    daemon_parser = subparsers.add_parser("daemon", help="Run multi-trigger daemon using a configuration file")
+    daemon_parser.add_argument("--config", default="triggers.json", help="Path to triggers.json configuration file")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(0)
+
+    console = Console()
+    client = HubClient()
+    runner = WorkerRunner(client=client)
+
+    if args.command == "info":
+        display.print_info(console, runner.get_system_info(), client)
+        sys.exit(0)
+
+    if args.command == "ping":
+        with console.status(f"Contacting {client.url or 'Hub'}..."):
+            result = client.ping()
+        display.print_ping(console, client, result)
+        sys.exit(0 if result["authorized"] else 1)
+
+    def start_heartbeats() -> None:
+        if client.enabled:
+            HeartbeatThread(client).start()
+            console.print(f"[dim]Sending heartbeats to {client.url} as '{client.worker_id}'[/]")
+
+    if args.command == "run":
+        extra_vars = {}
+        if args.vars:
+            try:
+                extra_vars = json.loads(args.vars)
+            except Exception as e:
+                print(f"Error parsing --vars JSON: {e}", file=sys.stderr)
+                sys.exit(1)
+
+        # Keep heartbeats going during long flows so the worker is not shown as offline mid-run
+        start_heartbeats()
+        try:
+            res = runner.execute_flow(
+                flow_path_or_alias=args.flow_path,
+                extra_vars=extra_vars,
+                use_sandbox=args.sandbox,
+                log_dir=args.log_dir
+            )
+
+            display.print_run_result(console, res)
+            sys.exit(1 if res["has_error"] else 0)
+
+        except Exception as e:
+            print(f"Worker execution failed with error: {e}", file=sys.stderr)
+            sys.exit(1)
+
+    if args.command == "watch":
+        from .triggers.watcher import FileWatcherTrigger
+
+        extra_vars = {}
+        if args.vars:
+            try:
+                extra_vars = json.loads(args.vars)
+            except Exception as e:
+                print(f"Error parsing --vars JSON: {e}", file=sys.stderr)
+                sys.exit(1)
+
+        watcher = FileWatcherTrigger(
+            watch_dir=args.directory,
+            flow_path=args.flow,
+            pattern=args.pattern,
+            poll_interval=args.interval,
+            use_sandbox=args.sandbox,
+            extra_vars=extra_vars,
+            runner=runner
+        )
+        print(f"Watching directory '{args.directory}' for pattern '{args.pattern}'...")
+        print(f"Target flow: {args.flow}")
+        print("Press Ctrl+C to stop.")
+        start_heartbeats()
+        watcher.run_loop()
+        sys.exit(0)
+
+    if args.command == "schedule":
+        from .triggers.scheduler import CronSchedulerTrigger
+
+        extra_vars = {}
+        if args.vars:
+            try:
+                extra_vars = json.loads(args.vars)
+            except Exception as e:
+                print(f"Error parsing --vars JSON: {e}", file=sys.stderr)
+                sys.exit(1)
+
+        try:
+            scheduler = CronSchedulerTrigger(
+                flow_path=args.flow,
+                interval_seconds=args.interval,
+                use_sandbox=args.sandbox,
+                extra_vars=extra_vars,
+                runner=runner,
+                cron=args.cron
+            )
+        except ValueError as e:
+            print(f"Invalid --cron: {e}", file=sys.stderr)
+            sys.exit(1)
+        print(f"Scheduled flow '{args.flow}' to run {scheduler.describe()}...")
+        print("Press Ctrl+C to stop.")
+        start_heartbeats()
+        scheduler.run_loop()
+        sys.exit(0)
+
+    if args.command == "daemon":
+        from .triggers.manager import TriggerManager
+
+        manager = TriggerManager(runner=runner)
+        try:
+            manager.load_from_config(args.config)
+            print(f"Loaded triggers from '{args.config}'. Running daemon...")
+            print("Press Ctrl+C to stop.")
+            start_heartbeats()
+            manager.start_all(blocking=True)
+            sys.exit(0)
+        except Exception as e:
+            print(f"Failed to start trigger daemon: {e}", file=sys.stderr)
+            sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
+