Skip to main content

​
Goal

Use iii.lock to replay registry-managed worker installs across local development, CI, and deployment environments.

​
Context

Use this when you add workers by registry shorthand, such as iii worker add image-resize or iii worker add image-resize@1.0.0, and you want every environment to use the same resolved worker graph.
iii.lock is written for registry-managed workers when the registry resolver returns a worker graph. Direct OCI image references, built-in workers, and local-path sandbox workers are not part of the current lockfile flow.

​
Steps

​
1. Add a Registry Worker

Add the worker from the iii registry. You can pin a requested version with @version, or omit it to resolve the registry default.
When the registry returns a resolved graph, the CLI updates both config.yaml and iii.lock.
config.yaml
iii.lock
If the resolved worker depends on other workers, those dependencies are recorded in the same lockfile.

​
2. Commit the Lockfile

Commit iii.lock with config.yaml so every environment has the same worker set and source pins.

​
3. Verify the Lockfile in CI

Run iii worker verify anywhere you need to confirm that registry-managed workers in config.yaml are represented in iii.lock.
The command succeeds when every lockfile-managed worker listed in config.yaml has an entry in iii.lock. Built-in workers, direct OCI image references, and local-path sandbox workers are ignored by this check because they are outside the current lockfile flow. Extra entries in iii.lock are allowed. For binary workers, iii.lock can carry artifacts for multiple target triples under the same resolved worker version. A lockfile generated on macOS can be reused on Linux CI when the registry resolver included a Linux artifact. If the current target is missing, verification fails with the missing target and the targets already present in the lockfile. You can use sync --frozen for the same non-mutating check:
Use strict verification when you also want dependency declarations checked against the locked versions:
Strict mode checks dependency ranges recorded in iii.lock and local iii.worker.yaml dependency blocks. It does not update pins; use iii worker update when you intentionally want new resolved versions.

​
4. Replay the Pinned Set

Run iii worker sync after cloning a repo, changing machines, or restoring CI/deployment state. The command reads iii.lock, installs or repairs registry-managed workers for the current platform, and verifies binary artifacts by SHA-256 before activation.
sync does not contact the registry resolver, does not refresh versions, and does not rewrite config.yaml or iii.lock. It reports installed, already-current, repaired, skipped, and failed workers. Built-ins, direct OCI image references, local-path workers, and sandbox rootfs/base images are skipped because they are outside the v1 lockfile replay contract.

​
5. Update Pins Intentionally

Update one locked worker by name:
Or update every locked root worker:
update re-resolves latest for the selected locked worker, or for each inferred root worker when no name is provided, and rewrites iii.lock with the new resolved graph. Dependency-only lockfile entries are refreshed through their root graph instead of being updated as independent roots.

​
Result

Your registry-managed workers are recorded in iii.lock, iii worker sync can replay them from trusted registry artifact URLs, CI can verify that config.yaml and the lockfile agree, and worker updates happen through explicit iii worker update commands.
For the full lockfile schema and command summary, see Managed Worker Lockfile.