Enroll a worker on a host

This guide is for a worker running separately from the leader. A standalone deployment enrolls its own worker automatically. To run workers in a cluster, see Enroll workers on Kubernetes.

Run the leader and its workers from one major release: verified binaries, or image digests from ghcr.io/smeltr-sh/smeltr. A worker on another major keeps running what it has and takes no new deployment, and Status shows it as On another build with both releases. A build that is not a release matches only its own commit.

The leader trusts an enrolled worker with every group's configuration and every credential it stores. Worker groups organize processing; use separate Smeltr clusters when you must isolate hosts from one another's configuration or credentials.

Prepare the group and host

Install that Smeltr executable or image on the worker host. Its built-in Git client fetches configuration from the leader. For a container, mount the configuration read-only and the worker state directory read-write outside the container. Give each worker its own state directory and preserve it across restarts. Never copy an enrolled worker’s state to another machine. The host must be able to connect to the leader, sources, and destinations.

Use the default group for a first installation. For another group, open Admin → Worker groups, choose + Add group, enter Name and Id, then choose Add. Review and deploy that change: a Pending group is not live until you deploy it.

Group name changes also need deployment; group colors apply immediately. Deleting a group also needs deployment. Once it deploys, workers still in that group stop all their pipelines until you move them to another group or shut them down. Set worker.group to the group ID. Shared configuration can affect more than one group, so inspect the full change before deploying.

Create an enrollment code

An enrollment code is the value that lets a new worker connect to the leader and obtain its own credential.

  1. Open Admin → Workers → Enrollment codes and choose + Add enrollment code.
  2. Set Group and Workers it brings in. A Permanent enrollment code also takes Workers and Valid for (hours); defaults are one worker and 24 hours. An Ephemeral one takes neither. No enrollment code outlasts the leader's certificate authority. Then select Mint.
  3. Correct “The address this worker will reach the leader at” to a URL reachable from the worker. A browser's localhost URL is not suitable for a remote worker.
  4. Copy the enrollment code before dismissing it. Smeltr shows the secret once and cannot retrieve it.

The enrollment code includes a secret and tells the worker how to verify the leader's certificate. A permanent enrollment code works until it expires, you withdraw it, or it reaches its allowed number of workers. An ephemeral one works until you withdraw it, for workers an autoscaler starts and stops; see Autoscale workers. Either stops working when the leader's certificate authority is replaced.

Configure and start

Save this as the worker’s configuration. Replace the placeholder with the complete enrollment code you copied. This example uses the direct HTTPS leader from the installation guide:

[worker]
enabled = true
group = "default"
enrollment_code = "PASTE_THE_COMPLETE_ENROLLMENT_CODE_HERE"

[worker.leader]
url = "https://smeltr.example.com"

[worker.storage]
state_dir = "/var/lib/smeltr-worker"
SMELTR_CONFIG_FILE=/absolute/path/to/worker.toml /absolute/path/to/smeltr

A worker whose group runs a receiver listens on the receiver's port, so the host's firewall must let senders reach that port.

For a container worker, set SMELTR_CONFIG_FILE to its mounted configuration path and mount /var/lib/smeltr-worker persistently. The container needs no inbound published port unless its group runs a receiver; then publish the receiver's port, for example -p 8088:8088. It must be able to reach the leader and every configured source and destination.

Leave worker.leader.ca unset for normal enrollment. An enrollment code either verifies the leader’s CA fingerprint and saves the matching certificate, or uses the operating system’s trusted certificates. If you set a CA file yourself, you must maintain it when the authority changes; automatic updates no longer apply. Keep certificate verification enabled.

After enrollment, the state directory contains worker_id, credential.token, the configuration clone and trust material. Protect it. After enrollment, the worker uses its saved credential. Remove a permanent enrollment code from configuration, restart the worker, and confirm it reconnects. A fresh host or lost state needs a new enrollment.

Verify and handle failures

On Status, confirm the worker is Online, reports the expected group, and shows its deployment state. Enrollment alone does not prove that a pipeline is running. A new worker must complete its first check-in and fetch configuration. A running worker keeps running through a leader outage; by default it does not stop solely because the leader is unreachable. A worker that restarts runs nothing until the leader answers its first check-in. See stop_after_unreachable_secs.

If enrollment fails, check the URL, the complete enrollment code, lifetime, remaining uses, group and certificate name. Withdraw an exposed enrollment code in the Enrollment codes table and mint another. Withdrawal prevents further enrollment but does not revoke workers already enrolled.

Revoke or replace a worker

Stop or isolate a compromised worker through your host-management controls, then select Revoke for that worker in Admin → Workers. Revocation refuses subsequent leader requests; it does not stop its running pipeline or its access to external data systems. Rotate external credentials where necessary. Enroll a rebuilt host using a new state directory and enrollment code, rather than reusing the revoked identity.