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. Compose reads it when preparing a path:// worker or a
registry package. 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 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.
For managed and reusable workers, configure the namespace in the compose file that deploys the
worker rather than baking it into the shipped worker. Set III_NAMESPACE in the worker service’s
environment; the SDK reads it when no explicit namespace option is passed. config.yaml does not
support a per-worker namespace: key.
When registering a worker programmatically, you may instead pass namespace directly to
registerWorker / register_worker. The explicit option takes precedence over III_NAMESPACE.
When neither is set, the worker registers in the default namespace.
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 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, and manifest 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 terms someone would
search for rather than repeating the worker description. 
