Worker identity and namespaces
A worker’s identity is(namespace, name). Two namespaces may use the same name; within one
namespace the name is exclusive. A duplicate live owner is rejected with
WORKER_NAMESPACE_CONFLICT.
The namespace: field in worker-compose.yaml selects the namespace for its containers. The
Compose daemon’s --namespace separately addresses that daemon’s compose::* functions.
Declare workers with Compose
Project workers live undercontainers: in worker-compose.yaml:
path:// workers use scripts.run from the Compose
file or scripts.start from their iii.worker.yaml manifest.
Start a project and keep its daemon in the foreground:
build downloads all declared package:// workers before startup. --up then reuses the shared
package cache. The command skips local path:// workers.
The presence of engine: makes the daemon own and stop the engine. Without it, pass --engine or
set III_URL to connect to an engine managed elsewhere.
Add a registry worker
compose::add resolves the package graph, writes exact versions into the Compose file, and restarts
the project:
file=/absolute/path/worker-compose.yaml when the daemon’s working directory is not the
project directory. A registry root whose kind is engine is rejected because the engine already
supplies it.
Find published workers at workers.iii.dev and inspect a package’s page
before adding it.
Operate workers
compose::restart worker= restarts one container. compose::update worker= edits the package pin
and restarts the project. compose::down stops containers in reverse dependency order.
Use engine::workers::list and engine::workers::info for the engine’s live connection view. Use
compose::status for process ownership, PID, and the last supervisor error.
Use iii compose logs <worker> --follow --namespace <daemon> for live raw stdout and stderr.
Configuration
Packages ship defaults. A container can name its configuration-worker entry withconfig_name and
override values with config_override. Precedence is package default, stored configuration value,
then config_override.
III_CONFIG_NAME, without persisting it. Workers read it through configuration::get.
Explicit saves persist the submitted value. See Configuration.
Engine-managed exceptions
configuration, iii-worker-manager, iii-http-functions, iii-stream, and iii-sandbox remain
engine-owned. Put them under engine.workers for managed Compose, or in config.yaml only when an
external supervisor owns the engine. Internal iii-engine-functions, iii-telemetry, and
iii-observability are injected automatically. They must not be added as Compose package roots.
To admit untrusted workers, browsers, or agents, keep the engine port internal and add the
rbac-proxy worker with
iii trigger compose::add worker=rbac-proxy. It opens its own public port and applies the engine’s
RBAC rules (authentication, function gating, registration hooks, filtered discovery) in front of the
existing engine port.
Workers outside Compose
Compose is optional for a process managed by Kubernetes, systemd, another host, or an SDK-driven development command. Give it the engine URL and a worker name; once connected it participates in the same function and trigger registry. Compose only owns processes declared in its file.Migrating an existing project
0.23 removediii worker, worker::*, and engine-side startup of project workers. Follow the
manual migration guide before starting an older project.