Worker

The Clarive Worker is one of the available communication methods used for sending/retrieving files and running commands on remote servers.

The Worker is an executable file that needs to be installed in each server in your network where you may want to run certain DevOps operations, which typically are executing local shell commands, sending files (ship) and retrieving files (fetch).

The Worker is a pull agent, meaning it initiates the connection to the Clarive pubsub server and awaits for instructions. It is ideal for cases where the server hosting the worker runs behind a firewall and is not directly reacheable by the Clarive server through SSH or a push agent such as ClaX.

Supported OS/Platforms¶

The Worker supports 3 main platforms:

Linux releases 2.6 or greater, including CentOS 5.x or greater
Windows 7.x, 8.x, 10.x and Windows Server 2003 or greater
MacOS 10.12 or greater

Pre-built binaries are available for both amd64 and arm64 architectures on all three platforms.

Installing the Worker¶

The Clarive Worker is a single binary and has no specific prerequisites. The only requisite is that the server where the worker is being installed can reach the Clarive server directly.

Typically the process to connecting your Clarive Server to the rest of your infrastructure for building, deploying and other DevOps-related activities is this:

Download the Clarive Worker binary cla-worker to the server
Register the worker with the server by using the global passkey
Start the worker online or as a daemon
Run your Clarive rules and pipeline against the worker

Clarive server requisites¶

For the worker to be able to connect, the Clarive web server must be running with the pubsub module active.

By default the pubsub module is active and starts with the rest of cla web-start web services.

Worker Capabilities¶

A worker instance can execute the following actions on its host server:

receive a remote file from the Clarive server and write it locally
send a local file to the Clarive server
run any arbitary command locally on the server as requested by the Clarive server
eval arbitary Javascript instructions on the server, using exposed or imported NodeJS libraries
report its tags so the server can route jobs by capability

Worker Security¶

The Worker only runs as the current OS user it has been launched with. But commands send by the server could escalate permissions if the user or executable have some type sudo permissions, sticky bit or similar mechanism.

Download the Worker¶

The Clarive Worker is open source and can be downloaded from the Clarive Github account:

 https://github.com/clarive/cla-worker/releases

The worker is a single static binary with no runtime dependencies. Pre-built releases are published for every supported platform and architecture:

Platform	Archive
Linux x64	`cla-worker-linux-x64.tar.gz`
Linux arm64	`cla-worker-linux-arm64.tar.gz`
macOS x64 (Intel)	`cla-worker-darwin-x64.tar.gz`
macOS arm64 (Apple Silicon)	`cla-worker-darwin-arm64.tar.gz`
Windows x64	`cla-worker-windows-x64.zip`
Windows arm64	`cla-worker-windows-arm64.zip`

Download the archive for your platform and extract it. The archive contains a single executable named cla-worker (or cla-worker.exe on Windows). Move it to a permanent location on disk — typical choices are:

/opt/cla-worker/cla-worker on Linux
/usr/local/cla-worker/cla-worker on macOS
C:\cla-worker\cla-worker.exe on Windows

Make sure the binary has execute permissions on Linux and macOS:

chmod +x cla-worker

You can verify the installation with:

cla-worker version

Registering the Worker¶

For a worker to connect to a Clarive server it needs a global passkey. The passkey is generated by a Clarive administrator.

To get the passkey, go to Admin > System > Workers and click the Register Worker button. A modal will appear with the registration command including the passkey and server URL.

cla-worker register --passkey (your passkey) --url (url to your server) --save

Copy the registration command and paste it to a terminal where you decompressed the cla-worker binary to register your worker.

By default, the worker will automatically detect the current OS username and hostname, and use them to generate the worker ID in the format user@hostname (e.g. joe@server1). These values are also sent to the server to populate the worker's user and server fields.

Important

Once generated, the passkey should be kept secret, as it could allow a intruder to register a worker and hijack deployment tasks. You can invalidate a registration passkey by opening the Register Worker section and hitting the Invalidate button if you suspect that the passkey is or could be compromised.

The registration process will return an ID-token pair that is unique to this worker instance.

Registration token: 97d317df5ad3fbb68334657ec94aefe6

Start the worker with:
  cla-worker run --token 97d317df5ad3fbb68334657ec94aefe6 --id joe@server1

To remove this registration:
  cla-worker unregister --token 97d317df5ad3fbb68334657ec94aefe6 --id joe@server1

The registration token returned is the worker "password" to access the server under a given ID.

If you used the option --save during the registration, the registration data (including the server URL) will be saved in a cla-worker.toml file in the current directory. To save in YAML format instead, use --save-format=yaml.

When a correctly registered config file exists, you can simply start it with:

 cla-worker run

If only one registration exists in the config file, the worker will automatically select it — no --id flag is needed.

If your config file is in another path, use --config or -c:

 cla-worker run -c /path/to/cla-worker.toml

The server URL is stored alongside each registration in the config file, so it will be used automatically when that registration is selected. Keep the config file permissions secure from prying eyes, as it contains your registration token.

Important

The ID-worker pair is analogous to a username/password for your worker instance. Keep it in a safe place. If it's compromised an attacker could impersonate the worker by making the Clarive Server believe it's connected to the correct server when in fact it's connected to the attacker's infrasctructure. That could end up with sensitive information or files being sent by the Clarive Server to the compromised worker.

Worker ID restrictions¶

The worker ID is used in URL query parameters, file paths (pidfile, logfile) and as a service identifier. Avoid the following characters in worker IDs:

Spaces — will break command-line arguments and URL parameters
Slashes (/ and \) — will break file paths used for pidfiles and logfiles
URL-reserved characters (?, &, #, %) — will break server communication
Quotes (", ', `) — will break shell commands and config file parsing
Newlines, tabs or other control characters — will break config parsing

Safe characters include letters, digits, hyphens (-), underscores (_), dots (.) and the at sign (@). The default auto-generated ID format user@hostname (e.g. joe@server1) uses only safe characters.

Examples of valid IDs:

joe@server1
build-worker-01
deploy_prod.us-east

Examples of problematic IDs:

my worker        (spaces)
prod/deploy      (slashes)
worker?id=1      (URL-reserved characters)

Config file¶

To keep your registrations safe, use a config file (cla-worker.toml or cla-worker.yml).

The config file is loaded from the following locations, in order of precedence:

from the parameter --config filepath or -c /path/to/cla-worker.toml
from the environment variable CLA_WORKER_CONFIG=/path/to/cla-worker.toml
from the current working directory (cla-worker.yml then cla-worker.toml)
from the user's home directory (environment variable HOME)
from /etc/cla-worker.yml or /etc/cla-worker.toml

To save your registration directly to a config file, use the --save flag:

 cla-worker register --save --passkey 123428198291ad98d98c89b8

By default, --save creates a TOML file (cla-worker.toml). To use YAML format instead:

 cla-worker register --save --save-format=yaml --passkey 123428198291ad98d98c89b8

Structure of the config file¶

These are the configuration parameters allowed in the config file:

Parameter	Description
`id`	the unique identifier of the worker (default: `user@hostname`)
`token`	the token returned by the registration process
`url`	the Clarive server URL (default: `http://localhost:8080`)
`passkey`	the access key for registering workers
`verbose`	verbosity level: `0` = INFO (default), `1`+ = DEBUG
`tags`	a comma separated list or array of tags
`origin`	origin identifier (default: `user@host/pid`)
`server`	bind to a Clarive server resource by name (default: OS hostname)
`server_mid`	bind to a Clarive server resource by MID
`no_server`	do not bind to any server resource (`true`/`false`)
`user`	the OS user for the worker (default: current user)
`name`	worker name (default: `user@hostname`)
`logfile`	path to log file
`pidfile`	path to PID file
`chunk_size`	file transfer chunk size in bytes (default: `65536`)
`allow_verbs`	list of allowed verbs (`exec`, `eval`, `get_file`, `put_file`, `file_exists`)
`deny_verbs`	list of denied verbs
`registrations`	list of saved registrations, each with `id`, `token`, and `url`

Each registration entry stores the server URL it was registered against, so when the worker auto-selects or matches a registration, the correct URL is used automatically.

Example TOML config with a single registration:

[[registrations]]
id = "joe@server1"
token = "97d317df5ad3fbb68334657ec94aefe6"
url = "http://clarive.example.com:8080"

Example YAML config with multiple registrations:

registrations:
  - id: joe@server1
    token: 97d317df5ad3fbb68334657ec94aefe6
    url: http://clarive.example.com:8080
  - id: joe@server2
    token: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
    url: http://clarive-eu.example.com:8080

Verb control¶

You can restrict which operations the worker is allowed to perform using the allow_verbs and deny_verbs configuration parameters. The controlled verbs are: exec, eval, get_file, put_file, file_exists.

If allow_verbs is not set, all verbs are allowed by default. deny_verbs entries are removed from the allowed set. Deny takes precedence over allow.

Example — allow only command execution and file retrieval:

allow_verbs = ["exec", "get_file"]

Example — allow everything except eval:

deny_verbs = ["eval"]

Assigning an ID to the Worker¶

Every worker, once registered, will have an ID automatically generated from the current OS username and hostname in the format user@hostname (e.g. joe@server1).

To override this, you can optionally assign a custom unique ID:

cla-worker register --id myworker --passkey 2323928198291ad98d98c89b8

Or use the --name flag:

cla-worker register --name myworker --passkey 2323928198291ad98d98c89b8

See Worker ID restrictions above for which characters are safe to use.

Binding to a Server Resource¶

By default, the worker's hostname is sent during registration and the server will attempt to match it to an existing Clarive server resource. If a match is found, the worker is automatically bound to that server resource.

To bind to a specific server resource by name (overriding the hostname):

cla-worker register --server myserver --passkey 2323928198291ad98d98c89b8

To bind to a server resource by its MID:

cla-worker register --server-mid MID123 --passkey 2323928198291ad98d98c89b8

To skip server binding entirely:

cla-worker register --no-server --passkey 2323928198291ad98d98c89b8

Command Reference¶

Below is a detailed reference for every cla-worker subcommand.

`cla-worker register`¶

Registers the worker with a Clarive server using a passkey. On success the server returns an ID-token pair that authenticates this worker.

cla-worker register [flags]

Flag	Description
`--passkey STRING`	(required) server registration passkey
`--url STRING`	base server URL (default: `http://localhost:8080`)
`--id STRING`	custom worker ID (default: `user@hostname`)
`--name STRING`	worker name, used as ID if `--id` not set
`--save`	save registration (id, token, url) to config file
`--save-format STRING`	config format for `--save`: `yaml` or `toml` (default: `toml`)
`--tags STRING`	comma-separated worker tags
`--origin STRING`	origin identifier (default: `user@host/pid`)
`--server STRING`	bind to a server resource by name (default: OS hostname)
`--server-mid STRING`	bind to a server resource by MID
`--no-server`	do not bind to any server resource
`--user STRING`	OS user for the worker (default: current user)

Example:

cla-worker register \
  --url https://clarive.example.com \
  --passkey abc123def456 \
  --tags linux,docker \
  --save

`cla-worker unregister`¶

Removes a worker registration from the server. Both the worker ID and its token are required for authentication.

cla-worker unregister [flags]

Flag	Description
`--url STRING`	base server URL
`--id STRING`	worker ID to unregister
`--token STRING`	authentication token for the worker
`--origin STRING`	origin identifier

Example:

cla-worker unregister --id joe@server1 --token 97d317df5ad3fbb68334657ec94aefe6

You must know the token corresponding to the id to be able to unregister a worker. Administrators can also unregister workers from the UI in Admin > System > Workers.

`cla-worker run`¶

Starts the worker and connects to the Clarive server. This is the main command used to run the worker. By default it runs in the foreground; use --daemon to fork into the background.

cla-worker run [flags]

Flag	Description
`--url STRING`	base server URL
`--id STRING`	worker ID
`--token STRING`	authentication token
`--tags STRING`	comma-separated worker tags
`--daemon`	run the worker in the background (fork)
`--logfile STRING`	path to log file (used in daemon mode)
`--pidfile STRING`	path to PID file (used in daemon mode)
`-v`	increase verbosity (DEBUG level)

If --id is not specified, the worker resolves it from the config file. When only one registration exists, it is selected automatically. If no config match is found, the ID is auto-detected as user@hostname.

Examples:

# Simple run with config file
cla-worker run

# Explicit ID and token
cla-worker run --id joe@server1 --token 97d317df5ad3fbb68334657ec94aefe6

# Select a specific registration from config
cla-worker run --id joe@server1

# Run as a background daemon
cla-worker run --daemon --logfile /var/log/cla-worker.log

# Run with debug output
cla-worker run -v

`cla-worker start`¶

Starts the Clarive Worker as an OS service. The service must have been previously installed with cla-worker install.

cla-worker start

This command delegates to the OS service manager:

Linux: systemctl start cla-worker
macOS: launchctl start the LaunchAgent
Windows: starts the registered Windows Service

`cla-worker stop`¶

Stops the Clarive Worker daemon by reading the PID file and sending a termination signal. The worker waits up to 10 seconds for a graceful shutdown before being killed.

cla-worker stop [flags]

Flag	Description
`--pidfile STRING`	path to PID file

The stop command will look for the pidfile in the default location. If the pidfile sits somewhere else, pass the path explicitly:

cla-worker stop --pidfile /var/run/cla-worker.pid

`cla-worker status`¶

Reports whether the worker daemon is currently running by checking the PID file.

cla-worker status [flags]

Flag	Description
`--id STRING`	worker ID (required)
`--pidfile STRING`	path to PID file
`--logfile STRING`	path to log file

Example:

$ cla-worker status --id joe@server1
checking status for workerId=joe@server1 pidfile=/opt/cla-worker/cla-worker.pid
worker is running with pid=27532

`cla-worker install`¶

Installs the Clarive Worker as a system service so it starts automatically on boot. See the Linux service installation, macOS service installation and Windows service installation sections below for platform-specific details.

cla-worker install [flags]

Flag	Description
`--id STRING`	worker ID to use when the service starts

The install command copies the current config to a system-level location (/etc/cla-worker.toml on Linux and macOS, %ProgramData%\cla-worker\cla-worker.toml on Windows) with the top-level id and url fields filled in, then registers the service with the OS service manager using the current executable path. The service is configured to run cla-worker run --id <id> --config <sys-path> on startup.

Copying the config to a system path is required because service managers such as systemd and launchd run the binary from a neutral working directory and cannot see a relative config file placed next to the binary.

Example:

cla-worker install --id joe@server1 -c /opt/cla-worker/cla-worker.toml

`cla-worker remove`¶

Removes the previously installed Clarive Worker system service.

cla-worker remove

This unregisters the service from the OS service manager. On Linux it removes the systemd unit file; on Windows it removes the Windows Service registration; on macOS it removes the LaunchAgent plist.

`cla-worker version`¶

Prints the worker version and build information.

cla-worker version

Example output:

cla-worker 2.0.2 (abc1234)

Global Flags¶

These flags are available on all subcommands:

Flag	Description
`-c, --config STRING`	path to config file
`--url STRING`	base server URL
`--id STRING`	worker ID
`--token STRING`	authentication token
`--passkey STRING`	registration passkey
`--tags STRING`	comma-separated worker tags
`--origin STRING`	origin identifier
`-v, --verbose`	increase verbosity (can be repeated)
`--logfile STRING`	path to log file
`--pidfile STRING`	path to PID file
`--allow-verbs STRING`	allowed verbs (comma-separated)
`--deny-verbs STRING`	denied verbs (comma-separated)

Running the worker¶

Once registered, the simplest way to start the worker is:

cla-worker run

This works when:

You used --save during registration (recommended), which stores the ID, token and URL in the config file.
Or the worker can auto-detect the ID from the current OS user and hostname (format: user@hostname), matching the registration default.

If only one registration exists in the config file and no --id is given, the worker automatically selects it — including the stored URL, token, and ID. No additional flags are needed.

If --id is not specified and cannot be resolved from the config file, the worker will auto-detect the ID as user@hostname and print it to the console.

You can also explicitly specify the ID and token:

cla-worker run --id joe@server1 --token 97d317df5ad3fbb68334657ec94aefe6

If you have multiple registrations in your config file, specify which one to use:

cla-worker run --id joe@server1

Worker management UI¶

Workers are centrally managed from the admin area at Admin > System > Workers. The same grid lists every worker registered against the Clarive server, regardless of which project uses it, since workers are global resources.

From there you can:

Obtain (or re-generate) the global passkey used to register workers.
Invalidate the passkey if you suspect it has been compromised; this does not affect workers that are already registered.
Monitor worker status and live connections. The grid shows whether each worker is online, disabled or has reported an error.
Edit a worker, which lets you rename it. Renaming re-keys the PubSub connection under the new ID so the worker keeps receiving jobs without a full reconnect.
Unregister workers, which removes the worker from the system. Unregistered workers are also removed from the resource catalog.
Shutdown workers, which kills the process on the remote servers.
Disable workers, which does not kill the process on the server but prevents new jobs from using it.
Execute ad-hoc commands via the REPL console on online workers, with a cancel-request button to abort long-running evaluations.

When a worker registers for the first time, a matching generic_server resource is automatically created in the catalog so it is immediately available as a deployment target.

Warning

Shutting down workers will kill the server process. After a shut down, restarting the worker requires manually logging into the server and starting the process — or having it installed as an OS service that gets restarted automatically.

Limiting Workers by environment¶

To limit what environments are available for a given worker, limiting it's usage to say QA or PROD, use the following flags in the cla-worker command line:

$ cla-worker run --id joe@server1 --envs QA,PROD

# Or by separating each entry:

$ cla-worker run --id joe@server1 --env QA --env PROD

Note

The environments need to exist in Clarive for the worker to start successfully. The environment names are case-sensitive.

Setting worker tags¶

Worker tags are useful to identify a worker capabilities. Then, when writing rulebooks that make use of a worker, you can ask for any available worker with a given capability.

Examples of useful tags could be java (can build java projects), gcc (C compiler), nodejs, etc.

$ cla-worker run --id joe@server1 --tags java,nodejs

# Or by separating each entry:

$ cla-worker run --id joe@server1 --tag java --tag nodejs

Then invoke your worker within a rulebook with the following options:

do:
    shell:
       worker: { tags: ['java'] }
       cmd: javac MyClass.java

This will run your command on the first worker that supports the tag java (meaning it has a Java compiler available):

One could have several workers within a given server, with different ids and tag sets for different capabilities.

Starting as a daemon¶

To run the Clarive Worker as a daemon, ie. to start the process in the background and get control back into the shell, run the following command:

cla-worker run --daemon --id joe@server1

The process id is stored in the pidfile while a detailed execution log is stored in logfile. These can be controlled by sending the option --logfile and --pidfile with the complete path to the files.

To check the status of the daemon, the cla-worker status command can come handy:

$ cla-worker status --id joe@server1
checking status for workerId=joe@server1 pidfile=/opt/cla-worker/cla-worker.pid
worker is running with pid=27532

To stop the worker daemon, use the following:

cla-worker stop --pidfile /opt/cla-worker/cla-worker.pid

The stop command will look for a pidfile in the default location for a given id. If the pidfile sits somewhere else, pass the stop command the path to the pidfile with cla-worker stop --pidfile [pidfile].

Debug mode¶

By default the worker logs at INFO level. Periodic heartbeat events (worker.connect) are logged once at startup and then suppressed to avoid noise. To see all messages, including heartbeats and internal diagnostics, enable debug mode using the -v flag or the verbose config field.

Using the command-line flag:

cla-worker run -v

Or in the config file:

verbose = 1

Installing as a Linux systemd service¶

On Linux the cla-worker install command creates a systemd unit file so the worker starts automatically on boot and can be managed with systemctl.

Prerequisites¶

A Linux distribution with systemd (most modern distributions)
The cla-worker binary placed in a permanent location (e.g. /opt/cla-worker/cla-worker)
A config file with a valid registration (e.g. /opt/cla-worker/cla-worker.toml)
Root or sudo access to install the service

Step-by-step¶

Place the binary and config file:

sudo mkdir -p /opt/cla-worker
sudo cp cla-worker /opt/cla-worker/
sudo chmod +x /opt/cla-worker/cla-worker

Register the worker (if not already done):

cd /opt/cla-worker
sudo ./cla-worker register \
  --url https://clarive.example.com \
  --passkey YOUR_PASSKEY \
  --save

Install the service:

cd /opt/cla-worker
sudo ./cla-worker install -c /opt/cla-worker/cla-worker.toml

This creates a systemd unit file at /etc/systemd/system/cla-worker.service that runs cla-worker run with the specified config file.

Start and enable the service:

sudo cla-worker start

Or directly with systemctl:

sudo systemctl enable cla-worker
sudo systemctl start cla-worker

Managing the service¶

# Check status
sudo systemctl status cla-worker

# View logs
sudo journalctl -u cla-worker -f

# Restart after config changes
sudo systemctl restart cla-worker

# Stop the service
sudo systemctl stop cla-worker

Removing the service¶

sudo systemctl stop cla-worker
sudo systemctl disable cla-worker
sudo /opt/cla-worker/cla-worker remove

Running as a dedicated user¶

For production deployments, consider running the worker under a dedicated system user instead of root:

sudo useradd -r -s /bin/false cla-worker
sudo chown -R cla-worker:cla-worker /opt/cla-worker

Then edit the systemd unit file to include:

[Service]
User=cla-worker
Group=cla-worker

And reload:

sudo systemctl daemon-reload
sudo systemctl restart cla-worker

Installing as a macOS launchd service¶

On macOS the cla-worker install command creates a launchd property list (.plist) so the worker starts automatically on boot and can be managed with launchctl. When installed as root the service is registered as a LaunchDaemon (system-wide, starts at boot before login). When installed as a regular user it is registered as a LaunchAgent tied to that user's session.

Prerequisites¶

macOS 10.12 or later
The cla-worker binary placed in a permanent location (e.g. /usr/local/cla-worker/cla-worker)
A config file with a valid registration (e.g. /usr/local/cla-worker/cla-worker.toml)
sudo access for a system-wide LaunchDaemon installation

Step-by-step (system-wide)¶

Place the binary and make it executable:

sudo mkdir -p /usr/local/cla-worker
sudo cp cla-worker /usr/local/cla-worker/
sudo chmod +x /usr/local/cla-worker/cla-worker

Register the worker (if not already done):

cd /usr/local/cla-worker
sudo ./cla-worker register \
  --url https://clarive.example.com \
  --passkey YOUR_PASSKEY \
  --save

Install the service:

cd /usr/local/cla-worker
sudo ./cla-worker install -c /usr/local/cla-worker/cla-worker.toml

This copies the config to /etc/cla-worker.toml and creates a LaunchDaemon plist at /Library/LaunchDaemons/cla-worker.plist that runs cla-worker run with the system config file. The service is loaded into launchd and configured to start on boot.

Start the service:

sudo cla-worker start

Or directly with launchctl:

sudo launchctl load /Library/LaunchDaemons/cla-worker.plist
sudo launchctl start cla-worker

Managing the service¶

# Check whether launchd has the service loaded
sudo launchctl list | grep cla-worker

# Stop the service
sudo cla-worker stop
# or
sudo launchctl stop cla-worker

# Restart the service
sudo launchctl stop cla-worker && sudo launchctl start cla-worker

# View live logs (default location)
tail -f /usr/local/cla-worker/cla-worker.log

Removing the service¶

sudo cla-worker stop
sudo cla-worker remove

This stops the daemon, unloads the plist from launchd and removes /Library/LaunchDaemons/cla-worker.plist.

Installing for a single user (LaunchAgent)¶

If you prefer the worker to run only while a specific user is logged in, install it without sudo. This creates a user-scoped LaunchAgent at ~/Library/LaunchAgents/cla-worker.plist:

cd ~/cla-worker
./cla-worker register --url https://clarive.example.com --passkey YOUR_PASSKEY --save
./cla-worker install -c ~/cla-worker/cla-worker.toml
cla-worker start

The LaunchAgent starts automatically when that user logs in and stops when they log out. To remove it:

cla-worker stop
cla-worker remove

Troubleshooting on macOS¶

If the service fails to start:

Check the log file for error details (defaults to cla-worker.log next to the config file, or look at the StandardErrorPath in the plist)
Verify the config file path is correct and readable by the user that runs the service
Run sudo launchctl list cla-worker to see the last exit status
Check Console.app under system.log for launchd messages
Ensure the binary is not quarantined by Gatekeeper; if it is, clear the attribute with xattr -d com.apple.quarantine /usr/local/cla-worker/cla-worker

Installing as a Windows service¶

On Windows the cla-worker install command registers the worker as a Windows Service so it starts automatically on boot and can be managed from the Services console (services.msc) or the sc command.

Prerequisites¶

Windows 7 or later, or Windows Server 2003 or later
The cla-worker.exe binary placed in a permanent location (e.g. C:\cla-worker\cla-worker.exe)
A config file with a valid registration (e.g. C:\cla-worker\cla-worker.toml)
An Administrator command prompt or PowerShell session

Step-by-step¶

Create a directory and place the binary:

mkdir C:\cla-worker
copy cla-worker.exe C:\cla-worker\

Register the worker (if not already done):

cd C:\cla-worker
.\cla-worker.exe register `
  --url https://clarive.example.com `
  --passkey YOUR_PASSKEY `
  --save

Install the service (run as Administrator):

cd C:\cla-worker
.\cla-worker.exe install -c C:\cla-worker\cla-worker.toml

This registers a Windows Service named cla-worker with display name Clarive Worker.

Start the service:

.\cla-worker.exe start

Or using the Windows service controller:

sc start cla-worker

The service will be configured to start automatically on boot.

Managing the service¶

# Check service status
sc query cla-worker

# Stop the service
sc stop cla-worker

# Restart the service
sc stop cla-worker && sc start cla-worker

You can also manage the service from the graphical Services console:

Press Win+R, type services.msc, press Enter
Find Clarive Worker in the list
Right-click to Start, Stop, Restart or change Properties

Viewing logs¶

When running as a Windows service, the default log path is C:\ProgramData\cla-worker\cla-worker.log. The directory is created automatically on startup so the service does not attempt to write into C:\Windows\System32, which is the default working directory of the Windows SCM.

To view logs in PowerShell:

Get-Content C:\ProgramData\cla-worker\cla-worker.log -Tail 50 -Wait

Log files are automatically rotated when they exceed max_log_size MB (default: 20). The current log is renamed to cla-worker.log.1 and a new log file is started. Only one backup is kept. To change the size limit, edit the config file:

max_log_size = 50

Running under a specific user¶

By default the service runs as Local System. To run it under a specific Windows user:

Open services.msc
Find Clarive Worker, right-click Properties
Go to the Log On tab
Select This account and enter the user credentials
Click OK and restart the service

Or from PowerShell (Administrator):

sc config cla-worker obj= "DOMAIN\username" password= "password"
sc stop cla-worker
sc start cla-worker

Removing the service¶

Stop the service first, then remove:

sc stop cla-worker
C:\cla-worker\cla-worker.exe remove

Troubleshooting¶

If the service fails to start:

Check the log file for error details
Verify the config file path is correct and accessible by the service user
Ensure the server URL is reachable from the Windows host
Check Windows Event Viewer (Application log) for service startup errors
Make sure the binary path has no spaces, or if it does, that the service was installed from that same path

Worker

Supported OS/Platforms¶

Installing the Worker¶

Clarive server requisites¶

Worker Capabilities¶

Worker Security¶

Download the Worker¶

Registering the Worker¶

Worker ID restrictions¶

Config file¶

Structure of the config file¶

Verb control¶

Assigning an ID to the Worker¶

Binding to a Server Resource¶

Command Reference¶

cla-worker register¶

cla-worker unregister¶

cla-worker run¶

cla-worker start¶

cla-worker stop¶

cla-worker status¶

cla-worker install¶

cla-worker remove¶

cla-worker version¶

Global Flags¶

Running the worker¶

Worker management UI¶

Limiting Workers by environment¶

Setting worker tags¶

Starting as a daemon¶

Debug mode¶

Installing as a Linux systemd service¶

Prerequisites¶

Step-by-step¶

Managing the service¶

Removing the service¶

Running as a dedicated user¶

Installing as a macOS launchd service¶

Prerequisites¶

Step-by-step (system-wide)¶

Managing the service¶

Removing the service¶

Installing for a single user (LaunchAgent)¶

Troubleshooting on macOS¶

Installing as a Windows service¶

Prerequisites¶

Step-by-step¶

Managing the service¶

Viewing logs¶

Running under a specific user¶

Removing the service¶

Troubleshooting¶

`cla-worker register`¶

`cla-worker unregister`¶

`cla-worker run`¶

`cla-worker start`¶

`cla-worker stop`¶

`cla-worker status`¶

`cla-worker install`¶

`cla-worker remove`¶

`cla-worker version`¶