System Process Runtime

worker-sys executes code directly as host OS processes without any container isolation. This is suitable for real-device control or scenarios where direct host access is required.

The current version of worker-sys is feature-complete in terms of capabilities and implementation. However, given its dangerous nature, we will not mark it as production-ready in the near term.

When to use

• You need direct access to host hardware or peripherals
• Container overhead is unacceptable
• You are running on a dedicated, trusted machine
• OpenClaw-like scenarios

Warning: worker-sys provides no sandbox isolation. Terminal commands execute directly on the host. Only run it on dedicated machines.

How it works

1. The worker connects to the control node over gRPC.
2. Execution requests are spawned as native OS processes on the host.
3. Process stdout/stderr is streamed back through the control plane.

An account can provision multiple worker-sys instances. Public computerUse calls select one with worker_id; omitting it lists all caller-owned instances and their online/offline state. Public readImage and exportFile calls use CU:<worker_id>. Console validates ownership and type, pins execution to that Worker without fallback, and translates the public session ID to the internal session_id="computerUse" value understood by worker-sys.

Shell selection (cross-platform)

computerUse runs commands through the host's system shell. The shell is selected per platform:

• Linux / macOS: /bin/sh -lc <command>
• Windows: powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -Command <command>, with [Console]::OutputEncoding and $OutputEncoding forced to UTF-8 so output is not garbled on systems whose default code page is not UTF-8 (e.g. GBK on Chinese Windows).

When deploying a Windows worker, entries in WORKER_COMPUTER_USE_COMMAND_WHITELIST must be in PowerShell form (e.g. Get-ChildItem, Get-Process) — Unix-style commands such as ls or cat will not match. The whitelist is matched as a literal prefix/exact string and must align with whatever shell the worker's platform uses.

Prerequisites

• Network access to the control node gRPC endpoint
• Appropriate OS-level permissions for the workloads you intend to run

Starting the worker

Download the latest worker-sys binary from the GitHub releases page, then run:

WORKER_CONSOLE_GRPC_TARGET=<console_grpc_target> \
WORKER_ID=<worker_id> \
WORKER_SECRET=<worker_secret> \
./onlyboxes-worker-sys

Set WORKER_CONSOLE_INSECURE=true when connecting without TLS.

Windows / PowerShell startup example:

$env:WORKER_CONSOLE_GRPC_TARGET = "<console_grpc_target>"
$env:WORKER_ID = "<worker_id>"
$env:WORKER_SECRET = "<worker_secret>"
.\onlyboxes-worker-sys.exe

Configuration file

The Worker Startup Tool in the dashboard can generate and download a ready-to-use config.toml. Set WORKER_CONFIG_FILE to use a specific file. If it is not set, the worker looks for config.toml next to the worker binary and then in the current working directory.

Environment variables take precedence over config.toml, which takes precedence over built-in defaults. TOML keys use the environment variable name without the WORKER_ prefix and in lowercase; arrays use native TOML arrays, and worker labels use a [labels] table.

id = "wk_..."
secret = "..."
console_grpc_target = "console.internal:50051"
computer_use_command_whitelist = ["echo", "time"]

[labels]
device = "lab-machine"

See the annotated configuration template for all available keys.

Environment variables

Connection

Identity

Computer use

Concurrency

computerUse and readImage use independent concurrency quotas, so an in-flight readImage does not consume a computerUse slot. Exceeding a capability's limit returns 409 session_busy.

Heartbeat

Logging

Related docs

• Architecture
• Docker Runtime
• Boxlite Runtime