Workers
Provision, inspect, resize, and remove customer-hosted project workers through the public API.
Loading documentation…
Powered by heyo
A worker runs restore checks for one project in your Kubernetes environment.
Create requires project_id, a lowercase name, a two-letter country, worker_runtime: "kubernetes", and specs.max_parallel_jobs from 1 to 64.
Worker creation returns a plaintext worker_token and installation descriptor.
The token is not returned again. Store and install it using the documented worker setup flow.
The public API can update a worker's name, description, and configured maximum parallel jobs. Country and runtime are immutable.
The worker's specs.max_parallel_jobs selects the generated agent Deployment's CPU, memory, and ephemeral-storage profile. Updating the API record alone does not change the Kubernetes Pod; apply the matching generated Deployment patch. Restore Job CPU and memory are configured separately on database schedules through database_resources. See CPU and memory for workers and Jobs.
List filters support name, status, country, and worker_runtime. Detail responses include public capacity and installation information.
Workers have no scratch size: each schedule's scratch_size_gi sets it. The scratch StorageClass is configured in the agent Deployment; the worker PATCH endpoint changes metadata and parallel capacity, not scratch storage.
List and detail responses can include agent_image_digest, the sha256:<hex> digest the agent reported when it last opened a session. agent_update compares that digest with the image reference supplied for new installations:
agent_update | Meaning |
|---|---|
current | The reported digest matches the available image. |
available | The digest differs or the agent could not report one. Update the image in your cluster. |
required | The agent lacks the current execution capability and receives no checks until it is updated. |
agent_install holds the agent_namespace, job_namespace, and scratch_storage_class (empty for the cluster default) the agent reported at its last session open. A changed Deployment restarts the agent, so the next session reports the new values. The field is absent until an agent that reports them has connected.
agent_image_digest is absent if the agent could not read its own Pod. In that case, agent_update can still be available. The update field itself is absent before the worker's first connection or when the API has no image digest configured for comparison. Only digests are compared, so using a registry mirror with the same image does not trigger an update hint. The old agent_version field is no longer returned. Updates are manual; see Upgrade a worker.
The live agent-log action accepts tail from 10 to 500 lines and returns transient text with Cache-Control: no-store. It requires a live worker session and reads the current agent container log, not a stored worker-log archive. It can return conflict, busy, timeout, or unavailable responses when the worker is not ready to answer. Check execution logs remain available through the Checks API.
A worker with running checks cannot be deleted. Deleting a worker removes its control-plane record; follow the worker operations guide for customer-cluster cleanup expectations.
Required scopes are v1.workers:read, v1.workers:write, and v1.workers:delete.