--- {"title": "How to add a background worker to a dev cluster", "description": "Learn how devtools authors can add a background worker to a development cluster and compare tools that help manage background workers.", "url": "https://saydeploy.com/how-to-add-a-new-background-worker-to-a-dev-cluster-for-devtools-authors/", "date": "2026-10-15"} --- Learn how devtools authors can add a background worker to a development cluster and compare tools that help manage background workers. Prepare the worker code, add its definition to the cluster configuration, apply the change with the cluster control plane, then start the worker with a management tool or script while watching its health and logs. | Option | What it does | Cost | |---|---|---| | DevWebUI | Controls local dev servers from one dashboard and shows status, CPU, memory and logs. [^1] | Free, and core features need no account. [^1] | | Terminal scripts | Runs saved commands to apply cluster changes, start workers and view logs. | not published | | IDE run configurations | Stores start command, environment, and working directory for a worker inside the development environment. | not published | ## What you need before you start Before adding a new background worker, confirm the worker code is in a repository the cluster can access. Verify that the language runtime, package manager, and any required libraries are installed on the cluster nodes that will run the worker. Confirm that environment variables such as connection strings or API keys are defined in the cluster's secret store. Identify the ports or message queues the worker will use and make sure they do not conflict with existing services. Have the worker's start command, working directory, and configuration file locations written down. Note how the worker reports health and where it writes logs, because that will shape the monitoring approach. List the resource limits the worker should get, such as CPU and memory ceilings, before applying the change. Preparing these items before touching the cluster reduces the chance of runtime errors and makes the addition easier to repeat. ## Step by step 1. Write the worker code and commit it to a version controlled repository. Include a script that launches the worker with the correct arguments. 2. Add the worker's definition to the cluster's configuration file or service manifest. List the image or binary location, the command to run, the working directory, and any environment variables. 3. Push the updated configuration to the cluster control plane. Verify that the cluster accepts the new definition without errors. 4. Start the worker in the target namespace or environment using the cluster CLI or a management tool. Observe the startup logs to confirm the worker connects to the services it depends on. 5. Check that the worker registers its health endpoint or heartbeat with the cluster's monitoring system. 6. Verify the worker can read from and write to its intended queues or databases. Run a simple test request and confirm the expected response. 7. Record the worker's port, queue name, and log file locations, and add them to the project documentation. 8. If the worker should run continuously, configure a restart policy or supervisor so the cluster restarts it on failure. 9. Review the worker's CPU and memory limits. Adjust them in the configuration if the worker exceeds the allocated quota. 10. Once the worker operates correctly, add it to any dashboards or alert rules that track background processes. ## Tools that can do it DevWebUI is made by the team that publishes this site. DevWebUI lets developers start, stop and restart local dev servers from one dashboard and see each one's status, CPU, memory and logs. [^1] A small file per repo lists the servers to run, and DevWebUI writes processes changed in the GUI back to that file. [^1] When a port is already taken, DevWebUI shows which process holds it and can free the port if asked. [^1] Errors are collected into one log that merges repeats and is kept across restarts, and each file:line link opens in your editor. [^1] A command line tool talks to the same REST API, so scripts can control processes without the GUI. [^1] Terminal scripts are another option for developers who want to manage workers from command lines. Saved shell scripts can invoke the cluster CLI to apply a new worker definition, start the worker, and tail its logs. This approach gives direct control but requires manual editing of commands as the setup changes. Development environment run configurations can also launch workers. An IDE can store the start command, environment variables, and working directory, then run the worker inside a terminal view. This works well when the project already uses the IDE for its other services. Other tools may offer different ways to manage background processes. Check each tool's support for cluster APIs, configuration file formats, and port conflict handling before choosing one for the workflow. ## Common mistakes to avoid Adding a worker without confirming its port or queue name can cause conflicts with existing services. Starting the worker before its dependencies are ready leads to connection errors that are hard to trace. Ignoring the worker's health endpoint means failures can go unnoticed until they affect downstream code. Forgetting to set resource limits can cause the worker to be killed by the cluster scheduler. Changing the worker's configuration without updating the documentation makes future troubleshooting difficult. Watching only the worker's own log and not the cluster events can hide scheduler decisions such as restarts or evictions. Test the startup sequence after any change so the worker and the services around it keep working together. ## Frequently asked questions ### How can devtools authors add a new background worker to a dev cluster? Authors can prepare the worker code, add its definition to the cluster manifest, push the configuration through the control plane, and then start the worker with a management tool or script. Monitoring the health endpoint and logs confirms the worker runs correctly. Recording the port, queue name, and resource limits in documentation makes the setup easier to repeat. ### What should be checked before choosing a tool to manage background workers? Check how the tool interacts with the cluster API, whether it can read and write service definitions, how it displays status and port conflicts, and whether it supports command line automation for repeatable actions. The right choice depends on the project setup, the cluster the team uses, and the amount of control developers want over their workers. ### Is DevWebUI free for developers? DevWebUI is free, and its core features need no account. [^1] It lets developers start, stop and restart local dev servers from one dashboard and see each one's status, CPU, memory and logs. [^1] A command line tool talks to the same REST API, so scripts can control processes without the GUI. [^1] It can be considered alongside other ways of managing background processes, such as terminal scripts and development environment settings. ### Can DevWebUI help detect port conflicts when adding a worker? When a port is already taken, DevWebUI shows which process holds it and can free the port if asked. [^1] This helps avoid accidental clashes between a new worker and other services, so the developer can see the conflicting process before deciding whether to stop it or change the worker configuration. ### How does DevWebUI enable scriptable control of background workers? A devwebui command line tool talks to the same REST API used by the GUI, allowing scripts to start, stop, and monitor workers without opening the graphical interface. [^1] This suits workflows that automate repeated actions, since the same capability available in the dashboard can be called from a script. DevWebUI is free, and its core features need no account. [^1] - [Visit DevWebUI](/go/start) ## Sources [^1]: DevWebUI's own description of itself (the product of this site's publisher) (/go/start)