This page covers iii.worker.yaml configuration options. iii.worker.yaml exists at a worker’s
root and tells iii how to provision the worker’s runtime, install its dependencies, start its
process, and pass through configuration. The engine reads it when starting a worker from
config.yaml and when the
iii worker CLI starts, stops, or restarts a managed worker.For how to connect a worker into a project once its manifest exists, see
Creating Workers / Workers.
iii.worker.yaml is not needed to run a worker process directly (for example node ./myworker/src/index.js). A worker that connects to the engine with the SDK behaves identically
whether iii started it or not.
Required. Must satisfy the registry’s worker-name rules (the same validation the registry applies to
published names). A worker cannot list itself in dependencies.
Optional. Overrides the default OCI rootfs. Must be a valid OCI reference (alphanumerics plus
. _ - / : @ +, max 512 characters). Invalid references are dropped with a warning and the default
is used.
runtime: base_image: oven/bun:1 # From docker.io # Or a fully-qualified registry path, e.g. GitHub Container Registry: # base_image: ghcr.io/astral-sh/uv:bookworm-slim
Explicit lifecycle scripts. These define how to initialize a worker’s base environment (setup),
install a worker’s dependencies (install), and run a worker whenever it is started or restarted
(start).
When scripts is omitted, the engine infers install and start from runtime.kind and
runtime.package_manager. The per-field examples below show common values for each language.
Map of environment variables injected into the worker process. Keys and values must be strings. The
keys III_URL and III_ENGINE_URL are silently filtered out; the engine sets the connection URL
itself.
Each name must satisfy the registry’s worker-name validation.
Each range must be a valid semver version requirement (for example ^1.2, ~0.5.0, >=2 <3).
Duplicate keys are an error.
A worker cannot depend on itself.
Prerelease ranges are accepted syntactically, but the default registry resolver serves only stable
versions, so a prerelease range surfaces as version_not_found at resolve time.
Optional CPU and memory requests for the worker’s sandbox. Requests above the cap are clamped to the
cap. For bundle workers this emits a W182 BundleResourceClamped warning at install time.
