Running Custom Workers

A Custom Worker is a custom developed Worker executable that replaces (or is used in addition to) the Standard Worker which the CLI installs by default.

This guide will help you understand how to run and install Custom Workers. There are multiple options depending on your use case: running locally for development, or deploying to a Kubernetes cluster for production.

The guide assumes you are already familiar with setting up the Standard Worker executable.

Running Locally

Using `cub worker run`

The simplest way to run a custom worker locally is with cub worker run. This command automatically creates the worker (if it doesn't exist), sets up the required environment variables, and starts the executable:

cub worker run --space $SPACE --executable ./my-worker my-worker-name

The --executable flag specifies the path to your custom worker binary. You can also pass additional environment variables with -e:

cub worker run --space $SPACE \
  --executable ./my-worker \
  -e "MY_VAR=my-value" \
  my-worker-name

To run the worker in the background (daemon mode), add the -d flag:

cub worker run --space $SPACE \
  --executable ./my-worker \
  -d \
  my-worker-name

Stop a daemon worker with:

cub worker stop my-worker-name

Running directly with environment variables

For more control, you can set up the environment manually and run the executable directly. Use cub worker get-envs to fetch the worker credentials:

eval "$(cub worker get-envs --space $SPACE my-worker-name)"
./my-worker

This sets CONFIGHUB_WORKER_ID and CONFIGHUB_WORKER_SECRET in your shell. If your worker needs additional environment variables, set them before running the executable:

eval "$(cub worker get-envs --space $SPACE my-worker-name)"
export MY_VAR=my-value
./my-worker

Note: The worker must already exist in ConfigHub for get-envs to work. Create it first with cub worker create if needed.

Installing in a Kubernetes Cluster

Using `cub worker install`

The cub worker install command generates Kubernetes manifests for deploying a worker. It creates a Namespace, ServiceAccount, ClusterRoleBinding, Deployment, and Secret.

Step 1: Create the worker unit

cub worker install --space $SPACE \
  --unit my-worker-unit \
  --target $TARGET \
  --image my-registry/my-worker:latest \
  my-worker-name

This creates a ConfigHub unit containing the Kubernetes manifests for the worker. You can pass additional environment variables with -e:

cub worker install --space $SPACE \
  --unit my-worker-unit \
  --target $TARGET \
  --image my-registry/my-worker:latest \
  -e "MY_VAR=my-value" \
  my-worker-name

To use a different namespace (default is confighub):

cub worker install --space $SPACE \
  --unit my-worker-unit \
  --target $TARGET \
  -n my-worker-namespace \
  --image my-registry/my-worker:latest \
  my-worker-name

You can also then modify the configuration as desired, such as with functions via cub function do.

Step 2: Apply the worker unit

cub unit apply --space $SPACE my-worker-unit

This deploys the Kubernetes resources (Namespace, ServiceAccount, ClusterRoleBinding, Deployment) to the cluster. The Deployment will initially fail because the Secret containing worker credentials has not been installed yet.

Step 3: Install the secret

Wait for the Deployment to be created, then install the secret:

kubectl -n confighub wait --for=create deployment/my-worker-name --timeout=120s
cub worker install --space $SPACE \
  --export-secret-only \
  -n confighub \
  my-worker-name 2>/dev/null | kubectl apply -f -

Step 4: Wait for the worker to be ready

kubectl -n confighub rollout status deployment/my-worker-name --timeout=120s

You can also verify in ConfigHub:

cub worker list --space $SPACE

which will print something like this:

NAME              CONDITION       SPACE          LAST-SEEN
my-worker-name    Ready           default        2025-10-31 20:37:53

Alternative: Export and apply directly

If you don't want to store the worker configuration as a ConfigHub unit, you can export the manifest and apply it directly:

cub worker install --space $SPACE \
  --export --include-secret \
  --image my-registry/my-worker:latest \
  my-worker-name 2>/dev/null | kubectl apply -f -

kubectl -n confighub rollout status deployment/my-worker-name --timeout=120s

This exports the full manifest (including the Secret) and pipes it directly to kubectl apply.