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 only matters when iii provisions and runs the worker in its built-in
virtualization. If you run the worker process yourself, for example node ./myworker/src/index.js
on your own machine, container, or server, you do not need the manifest at all. Any process that
uses a iii SDK, calls registerWorker(), and connects to a iii instance is a worker, and behaves
identically whether iii started it or not.
name
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.
runtime
Declares details about the worker’s environment.
base_image
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.
scripts
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.
setup
Runs once when the sandbox is provisioned. Use it for system-level packages your dependencies need
to build.
install
Installs dependencies.
start
Starts the worker process.
env
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.
dependencies
Map of <worker-name>: <semver range> declaring other workers this worker depends on, resolved
against the registry.
Rules:
- 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.
resources
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.
cpus
Optional integer. Number of vCPUs. Defaults to 2, capped at 4.
memory
Optional integer. Memory in MiB. Defaults to 2048, capped at 4096.
Optional strings used by the workers-repository release pipeline, not by the engine. The engine
accepts these keys (so a manifest published from the workers repo also works with local
iii worker add) but never reads them.
