Worker

Workers are the distributed scanning engine of OASM. A worker is a small program that connects securely to the platform, authenticates with a workspace API key, and pulls scan jobs as capacity frees up. It executes the configured scanning tools, reports progress and results back to the platform, and lets you scale scanning horizontally by running more instances. Workers are stateless: they can join or leave the system at any time without affecting the platform, the Console, or other workers. This pull-based model makes the execution layer fault-tolerant — if a worker stops mid-job, the job stays visible in the Job Registry and can be re-run once the worker layer is healthy again.

​

Key concepts

​

How a worker connects

The connection is established once at startup and then kept alive for the lifetime of the process:

1. The worker starts and reads its connection settings.
2. It authenticates to the platform with the workspace API key.
3. It registers with the platform and starts pulling scan jobs.
4. It executes each job’s steps, reporting progress and results back.
5. The platform’s job registry tracks the job through each stage: waiting, running, and then finished successfully, failed, or cancelled.

Workers execute job steps grouped by category. Each job belongs to one of the scanning categories, and the worker runs the tools associated with it:

​

Connect a worker

​

Prerequisites

• A running platform that the worker can reach.
• A workspace API key. Generate or copy one from Settings → API Keys — see API keys.

​

Step-by-step

​

Run a worker with Docker Compose

The simplest path is the worker service shipped in the platform’s Docker Compose deployment. Configure the workspace API key and the connection settings for the platform, then start the worker service. The stack mounts a shared tools folder where the scanning tools are installed once and cached, so tool installation does not repeat for every job.

​

Run a worker from the Console

On the Workers page, use the Connect worker button. It shows a ready-to-run command for your environment, pre-filled with the workspace API key and the host you are browsing from. Options are available for running from source (DevMode), on Linux, and on Windows.

​

Worker scope

Each worker operates under a scope that determines which jobs it may pull: The Workers page shows workers under Global and Workspace tabs. A worker bound to a workspace serves that workspace’s jobs; a Global worker has access to jobs from any workspace.

​

Scaling workers

Workers scale horizontally without shared state — add instances and the platform distributes jobs among whoever is ready.

• Run more instances. Launch additional worker instances using the same workspace API key. Each pulls the next available job when it has capacity.
• Allow more parallel jobs on powerful hosts. The default concurrency setting bounds how many jobs one worker executes at once. Treat it as a per-host budget: raise it when the host has spare CPU and memory, lower it when jobs share tools or targets and you see timeouts.
• Prefer more instances over extreme concurrency. More instances spread load across machines; a very high concurrency value saturates one machine.

​

Connection settings

Workers authenticate with the workspace API key and read a small set of connection settings that point them at the platform and control how many jobs they run in parallel. The defaults match a standard deployment; change them only when your setup differs.

​

Troubleshooting

Jobs stay stuck in the waiting stage

A job only leaves the waiting stage when a connected worker picks it up. If jobs accumulate, check that at least one worker shows a connected status on the Workers page, then check the worker logs for registration errors. See Jobs for the full lifecycle.

The worker shows no connected status after starting

Confirm the API key is valid and belongs to the workspace: rotate it in Settings → API Keys if in doubt, update the worker’s connection settings, and restart the worker. Then check that the worker can reach the platform from its host.

The API key was rotated — the worker stopped pulling jobs

Rotation invalidates the previous key immediately, so the worker’s connection is rejected. Update the worker’s connection settings with the new key and restart the worker. Rotate keys on a schedule and update every worker (and other API consumers) before the old key is needed again.

The worker cannot reach the platform

Verify network connectivity from the worker host to the platform. In a Docker Compose deployment, the worker must be on the same network as the platform service.

​

Related