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=<name>@<selector> 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, and iii-stream (deprecated) 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,
iii-observability, and the iii-sandbox router are injected automatically. They must not be
added as Compose package roots. The router forwards sandbox::* calls to the sandbox-libkrun
worker, which Compose installs; an engine no Compose file manages sets a top-level sandbox:
section in its config.yaml, or those calls fail with S303 (see
Sandboxes).
To admit untrusted workers, browsers, or agents, keep the engine port internal and add the
rbac-proxy worker with
iii call 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.