iii.worker.yaml configuration options. iii.worker.yaml exists at a worker’s
root and gives iii what it needs to provision the worker’s runtime, install its dependencies, start
its process, and pass through configuration. At add time the schema is strict: an unknown key is an
error, and the error lists the supported fields.
Compose reads two fields from it: scripts.start and runtime.base_image. The worker provisioning
path reads the other fields. Project workers are declared and operated through
worker-compose.yaml, not the engine’s config.yaml.
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 host, you do not need the manifest at all. Any process that uses an iii SDK, calls
registerWorker(), and connects to an iii instance is a worker, and behaves identically whether
iii started it or not.name
Required. One path segment: ASCII alphanumerics, -, _ and .. A leading . and a .. sequence
are both errors.
description
Optional. One-line summary of the worker. iii prints it when it installs a worker from an image.
runtime
Declares details about the worker’s environment. base_image is the only supported field.
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
Lifecycle commands. setup runs once when the sandbox is provisioned, for the system packages a
dependency needs to build. install installs dependencies. start runs the worker process, and it
is required.
setup, install and start explicitly. The keys that fed the old inference path
(runtime.kind, runtime.package_manager, runtime.entry, runtime.language) are deprecated and
will be removed in a later version.
An omitted install skips the dependency install and prints a warning. install: "" skips it
without a warning.
A registry bundle manifest rejects
scripts.setup with W180 BundleManifestRejected. It accepts
scripts.install and runtime.base_image, and it rejects a base image that is not a plausible
OCI reference. See Registry / Bundling workers.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 filtered out; the engine sets the connection URL itself.
III_NAMESPACE) or the registration call sets it. See Namespaces.
dependencies
Map of <worker-name>: <semver range> declaring other workers this worker depends on, resolved
against the registry.
- Each name must satisfy the same rules as
name. - 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_foundat 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.
iii_engine_version
Optional string: the semver range of iii engines the worker runs on, like the engines field of a
Node package.json. Compose refuses to validate or start the worker (INCOMPATIBLE_ENGINE) when the
running iii engine is outside the range, and registry installs only pick versions whose range
includes it. A registry bundle is checked again each time it is installed, so one pinned in
worker-compose.lock before an iii update is refused too. The engine is compared by its MAJOR.MINOR.PATCH, so 0.26.0-rc.2 counts as 0.26.0.
A range is one or more comparators (>=, >, <=, <, =, ^, ~, or none, followed by
MAJOR.MINOR.PATCH). Comparators joined by spaces must all hold; sets joined by || may each
hold. A bare 0.26.0 means exactly that version, and ^0.26.0 means >=0.26.0 <0.27.0. No v
prefix, prerelease, x wildcard, or hyphen range.
Quote the value: YAML reads a leading > as a block scalar.
Publish metadata: iii, deploy, manifest, tags, license
Optional metadata 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 a local Compose
worker) but never reads them at runtime.
iii, deploy, manifest, and license are strings. tags is a list of strings used for agent
and user discovery in the workers registry. Keep tags short, lowercase, and focused on search terms
rather than repeating the worker description. license is an
SPDX license id, for example Apache-2.0. The release pipeline of the
workers repository requires it.