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:

​

Connector tools on a worker

Not every tool is built into the worker. A connector is an external security tool packaged as a container image. When a job targets a connector, the worker acts as a container supervisor:

1. The platform sends the run to the worker with the connector’s container image, its per-run inputs, and the resolved configuration.
2. The worker pulls the image if it is not already cached, then starts the container.
3. The container starts the connector, which dials back to the worker over a private endpoint. The connector never listens for inbound connections.
4. The connector registers, runs the scan, and streams findings back to the worker, which persists them through the platform.
5. When the run finishes, the outcome is recorded in the job registry.

​

Connector runtime requirements

• A container runtime. The worker needs access to a Docker daemon to start connector containers. In the production Compose stack the worker runs in node mode with the Docker socket mounted — see Deployment.
• A reachable dial address. Connector containers must be able to reach the worker at WORKER_CONNECTOR_ADDR (host:port). If the address is empty and autodetect is not enabled, the worker stops at startup rather than starting containers that could never connect.
• Optional authentication. Set WORKER_CONNECTOR_TOKEN for a shared-secret handshake, or enable mTLS on the connector endpoint.

​

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 shipped worker runs in node mode: it mounts the host Docker socket so it can start connector containers, and publishes the connector port so those containers can dial back to it. The stack also mounts a shared tools folder where the built-in 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. Workers that run connector containers read a few connector settings on top of these:

​

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.

Connector jobs fail to start

Connector runs need a worker that can start containers. Check that the worker has access to a Docker daemon, that its connector dial address is set, and that the connector image can be pulled from its registry. The worker log names the failing step — image pull, container start, or the connector’s registration.

Connector containers keep running after a job finishes

This is the warm pool keeping an idle container ready for the next job. Idle containers are stopped and removed after the idle timeout; lower the timeout if you want them cleared sooner.

​

Related