docbee-workpipe-runner 2026.1.2

Secure task execution runner for DocBee WorkPipe

DocBee WorkPipe Runner

A lightweight, secure task execution agent for DocBee WorkPipe. The runner polls your DocBee server for jobs, validates parameters, executes them locally (shell scripts, Python, Ansible, PowerShell, …), and reports results back — no inbound connections required.

---

Installation

pip install docbee-workpipe-runner

Requires Python 3.11 or newer.

---

Quick Start

# 1. Create config templates
docbee-workpipe-runner init

# 2. Set server URL and API key
nano .env

# 3. Define allowed tasks
nano tasks.yml

# 4. Start the worker
docbee-workpipe-runner start

---

Windows Quick Start

1. Install Python 3.11+

Download from python.org/downloads. During installation, check „Add Python to PATH" — this box is unchecked by default. Verify afterwards:

python --version

2. Create a working directory

Open Command Prompt as Administrator (Start → type cmd → right-click → Run as administrator):

mkdir C:\docbee-workpipe-runner
cd C:\docbee-workpipe-runner

3. Install and configure

pip install docbee-workpipe-runner
docbee-workpipe-runner init
notepad .env

Fill in DOCBEE_WORKPIPE_API_URL and DOCBEE_WORKPIPE_API_KEY. When saving with Notepad: File → Save As → Encoding: UTF-8 (not „UTF-8 with BOM").

4. Validate and start

docbee-workpipe-runner status
docbee-workpipe-runner start

Troubleshooting

Problem	Fix
'docbee-workpipe-runner' is not recognized	Python was installed without PATH. Use python -m pip install docbee-workpipe-runner, then python -m docbee_workpipe_runner start — or reinstall Python with PATH enabled.
pip not found	Use python -m pip install docbee-workpipe-runner
PowerShell tasks fail (not digitally signed)	Run once in an admin PowerShell: Set-ExecutionPolicy RemoteSigned -Scope LocalMachine

---

Configuration

All settings can be provided as environment variables, in a .env file, or as CLI flags.

Environment Variable	CLI Flag	Required	Default	Description
DOCBEE_WORKPIPE_API_URL	--api-url	✓	—	DocBee WorkPipe server URL
DOCBEE_WORKPIPE_API_KEY	--api-key	✓	—	Worker API token (ROLE_WORK_PIPE_WORKER)
DOCBEE_WORKPIPE_TASKS_FILE	--tasks-file	—	tasks.yml	Path to the task definition file
DOCBEE_WORKPIPE_POLL_INTERVAL	--poll	—	60	Seconds between job polls
DOCBEE_WORKPIPE_MAX_WORKERS	--workers	—	1	Maximum number of concurrent jobs
DOCBEE_WORKPIPE_LOG_DIR	--log-dir	—	logs	Directory for job log files
DOCBEE_WORKPIPE_STATE_DIR	--state-dir	—	~/.docbee-workpipe-runner	Directory for pinned server key + dedup cache
DOCBEE_WORKPIPE_SERVER_KEY_FINGERPRINT	--server-key-fingerprint	—	—	Optional: expected SHA256 fingerprint at first key pinning
DOCBEE_WORKPIPE_CLOCK_SKEW	—	—	30	Clock skew tolerance in seconds for expiresAt
DOCBEE_WORKPIPE_DEDUP_TTL	—	—	86400	TTL of the dedup cache in seconds

.env file (recommended)

DOCBEE_WORKPIPE_API_URL=https://your-docbee-server.com
DOCBEE_WORKPIPE_API_KEY=your-worker-token-here
DOCBEE_WORKPIPE_TASKS_FILE=tasks.yml
DOCBEE_WORKPIPE_POLL_INTERVAL=60
DOCBEE_WORKPIPE_MAX_WORKERS=1
DOCBEE_WORKPIPE_LOG_DIR=logs

# Optional hardening: enforce this fingerprint at first key pinning.
# Copy from the DocBee admin UI.
# DOCBEE_WORKPIPE_SERVER_KEY_FINGERPRINT=SHA256:xx:xx:...

---

Signed Job Dispatch (MITM & Replay Protection)

Every job response from the server is Ed25519-signed and carries an expiresAt timestamp and a unique nonce. The runner rejects any job that cannot be cryptographically verified — even when TLS is compromised by a corporate MITM proxy, a rogue CA, or a malicious network node.

On first heartbeat, the server's public key is pinned to <state_dir>/server_key.pub. The runner logs the SHA256 fingerprint for manual cross-verification against the DocBee admin UI. Rejections are recorded in audit.log as rejected_invalid_signature, rejected_expired_job, or rejected_replay.

To harden the first contact against a compromised initial TLS session, set DOCBEE_WORKPIPE_SERVER_KEY_FINGERPRINT in your .env to the fingerprint shown in the DocBee admin UI. The runner will refuse to pin any key that does not match.

When the server rotates its key, the runner halts polling with key_mismatch. Run docbee-workpipe-runner trust-new-key to accept the rotation after verifying the new fingerprint.

---

tasks.yml — Task Definitions

tasks.yml defines which tasks the worker accepts, how parameters are validated, and how results are returned. Only tasks defined here will be executed.

tasks:

  my_task:
    description: "Short description"
    result_type: text        # text or json (default: text)
    command: "echo {name}"   # shell command with {param} placeholders
    timeout: 30              # max runtime in seconds (default: 300)
    parameters:
      name:
        type: string
        required: true

Parameter types and validation rules

Type	Available rules
string	regex, min_length, max_length, required, default
integer	min, max, required, default
float	min, max, required, default
boolean	required, default
enum	values: [a, b, c], required, default

parameters:
  host:
    type: string
    regex: "^[a-zA-Z0-9._-]+$"
    required: true

  count:
    type: integer
    min: 1
    max: 10
    default: 3

  environment:
    type: enum
    values: [dev, staging, production]
    required: true

Security: Unknown parameters are automatically rejected. All values are escaped with shlex.quote() before substitution into the command.

---

Returning Results

Scripts return structured results via the ##RESULT## marker printed to stdout.

result_type: text (default)

echo "##RESULT## Deployment complete"

→ resultMessage: "Deployment complete"

result_type: json

echo '##RESULT## {"message": "3 servers updated", "servers": 3, "errors": 0}'

→ resultMessage: "3 servers updated", resultData: {"servers": 3, "errors": 0}

If no ##RESULT## marker is printed, the last line of stdout is used as resultMessage.

Error handling

If the script exits with a non-zero exit code, the last line of stderr (or stdout as fallback) is used as resultMessage and the job is marked as failed.

---

Logging

Job output is written to rotating log files in the configured --log-dir directory (default: logs/):

logs/
├── <task_name>.log    # Per-task rotating log (5 MB × 5 = 25 MB max per task)
└── audit.log          # All job events (10 MB × 10 = 100 MB max)

The audit log records ISO timestamp, event type, job ID, task name, parameters, command, duration, and result message for every job.

---

Running as a Service

Linux — systemd

# /etc/systemd/system/docbee-workpipe-runner.service
[Unit]
Description=DocBee WorkPipe Runner
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/docbee-worker
EnvironmentFile=/opt/docbee-worker/.env
ExecStartPre=pip install --upgrade docbee-workpipe-runner
ExecStart=docbee-workpipe-runner start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now docbee-workpipe-runner
sudo journalctl -fu docbee-workpipe-runner

Windows — Servy

Servy turns the worker into a proper Windows service that starts automatically with the system and restarts on failure. Download and install Servy from servy-win.github.io. servy-cli.exe must be available in your PATH.

First, find the full path to the installed CLI entry point:

where docbee-workpipe-runner

Run all commands in an Administrator PowerShell (substitute the path from above):

servy-cli install `
  --name="DocBeeWorkPipeRunner" `
  --path="C:\path\to\docbee-workpipe-runner.exe" `
  --params="start" `
  --startupDir="C:\docbee-workpipe-runner" `
  --startupType="Automatic" `
  --stdout="C:\docbee-workpipe-runner\logs\service.log" `
  --stderr="C:\docbee-workpipe-runner\logs\service.log" `
  --enableSizeRotation `
  --rotationSize="5" `
  --maxRotations="5"

servy-cli start --name="DocBeeWorkPipeRunner"

The .env file in C:\docbee-workpipe-runner\ is loaded automatically — no separate service environment configuration needed.

servy-cli status --name="DocBeeWorkPipeRunner"    # check service status
servy-cli restart --name="DocBeeWorkPipeRunner"   # restart service
servy-cli stop --name="DocBeeWorkPipeRunner"      # stop service
servy-cli uninstall --name="DocBeeWorkPipeRunner" # uninstall service

Docker

# docker-compose.yml
services:
  worker:
    image: python:3.12-slim
    command: >
      sh -c "pip install docbee-workpipe-runner && docbee-workpipe-runner start"
    environment:
      DOCBEE_WORKPIPE_API_URL: https://your-server.com
      DOCBEE_WORKPIPE_API_KEY: your-token
    volumes:
      - ./tasks.yml:/app/tasks.yml
      - ./scripts:/app/scripts
      - ./logs:/app/logs
    working_dir: /app
    restart: unless-stopped

---

CLI Commands

Command	Description
docbee-workpipe-runner start	Start the worker
docbee-workpipe-runner init	Create .env and tasks.yml templates
docbee-workpipe-runner status	Validate tasks.yml and list registered task types
docbee-workpipe-runner trust-new-key	Accept a rotated server public key after a key_mismatch halt
docbee-workpipe-runner update	Check for a newer version on PyPI
docbee-workpipe-runner --version	Show installed version

---

License

Proprietary — 2026 © DocBee. All rights reserved.