Skip to Content
OperateDeployArcade Worker

Arcade Worker

The Arcade Worker hosts Arcade’s toolkits and runs their calls for the Engine. In a self-hosted deployment it’s the bundled MCP server, and it appears as a workers[] entry in the Helm values.

This page explains how the worker behaves and when to change each setting. For every value and its default, see the chart reference on Artifact Hub , which is the source of truth.

Process models

The worker ships as two images built from the same commit. The image you choose is the worker’s process model:

ImageProcess model
arcadedev/worker-supervisorServes the tool catalog from a snapshot taken at build time, and starts one isolated runtime per toolkit version on demand. One worker can host multiple versions of the same toolkit.
arcadedev/workerEager: loads every toolkit into one process at boot.

How the supervisor worker behaves

Operators can rely on the following behavior from the arcadedev/worker-supervisor image.

Versions

  • A call that names a toolkit version runs on exactly that version. If the worker doesn’t offer that version, it refuses the call rather than serving it with another version.
  • A call that names no version runs on the highest version the worker offers.
  • Multiple versions of the same toolkit run side by side, and each serves only its own calls.

Errors

  • A call for a that the version doesn’t have, or for a toolkit the worker isn’t configured to serve, fails with an error that clients can’t retry.
  • If the worker can’t start or reach a runtime, the call fails with a generic retryable error that exposes no internal detail.
  • If a version can never start, the worker gives up on it after a bounded number of attempts. A version that fails to start never takes the worker down.

Lifecycle

  • If a runtime crashes, the worker recovers it on the next call.
  • The worker stops an idle runtime to reclaim memory and starts it again on demand.
  • The worker reports ready only after its pre-warm pass finishes, so the first callers after a deploy don’t wait for warm-up. The worker skips any pre-warm entry it can’t warm.
  • The worker publishes the of every version it serves, whether or not the version is running, without starting it.
  • When the worker stops, it answers calls already in flight, then stops every runtime it started.

Settings

Set these values under workerDefaults to apply them to every worker, or on an individual workers[] entry.

ValueDefaultWhat it controls and when to change it
supervisor.prewarmToolkitsEmptyToolkits started at boot and kept warm, at the highest version of each. Pre-warmed toolkits are exempt from idle eviction and restart if they die. List the toolkits your users call most, so they’re never served cold.
supervisor.serveToolkits*Toolkits this worker serves. The worker refuses calls for anything left off and leaves it out of the published tools. Use it to split a fleet, for example to run a dedicated worker for the most-called toolkits.
supervisor.maxChildren15The most runtimes running at once. At the cap, the worker stops the least recently used idle runtime that isn’t pre-warmed to admit a new one. 0 means unbounded. Size pod memory from this value, see Sizing.
supervisor.idleTtlSeconds600Seconds a runtime may sit idle before the worker stops it. 0 never stops an idle runtime.
supervisor.capacityWaitSeconds30How long a call waits for a free slot when every runtime is busy at the cap, before it fails with a retryable error.

Advanced settings

Set these environment variables through extraEnv. See the chart reference  for details.

VariableDefaultWhat it controls
ARCADE_PREWARM_TOOLKITSUnsetComma-separated toolkits to start at boot and keep warm, by catalog name (GoogleDocs) or package name (google-docs). The worker logs and skips names the image doesn’t offer. The chart sets this variable from supervisor.prewarmToolkits, so set one or the other, not both.
ARCADE_SERVE_TOOLKITSUnsetComma-separated toolkits this worker serves. Unset, empty, or * serves the whole catalog the image offers. The chart sets this variable from supervisor.serveToolkits, so set one or the other, not both.
ARCADE_SUPERVISOR_MAX_CHILDREN15The most runtimes running at once. 0 means unbounded. The chart always sets this variable from supervisor.maxChildren, so change that value instead of adding the variable to extraEnv.
ARCADE_SUPERVISOR_INVOKE_TIMEOUT600 secondsThe longest a single tool call may run.
ARCADE_SUPERVISOR_PREWARM_CONCURRENCY4How many runtimes start at once during boot. Keep it near the pod’s core count.

Sizing

  • Memory: each running runtime uses about 100 MB, so a pod needs roughly maxChildren × 100 MB plus memory for the supervisor itself, plus headroom.
  • Boot time: with ten pre-warmed toolkits on 2 cores, the supervisor worker is ready in about 12 seconds. The eager worker takes 60 seconds or more to load every toolkit.
  • Image size: the supervisor image is 2.96 GB. The eager worker plus the deprecated-versions worker it replaces total 3.85 GB.

Next steps

Last updated on
Self-host with HelmHybrid MCP servers