> ## Documentation Index
> Fetch the complete documentation index at: https://iii.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Worker manifest

> Complete field reference for iii.worker.yaml.

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. The engine reads it when starting a worker from
[`config.yaml`](../using-iii/engine#configuration-file-structure) and when the
[`iii worker`](../using-iii/workers) CLI starts, stops, or restarts a managed worker.

For how to connect a worker into a project once its manifest exists, see
[Creating Workers / Workers](./workers).

<Note>
  `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.
</Note>

## `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.

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
runtime:
  base_image: oven/bun:1 # From docker.io
  # Or a fully-qualified registry path, e.g. GitHub Container Registry:
  # base_image: ghcr.io/astral-sh/uv:bookworm-slim
```

## `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`).

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
scripts:
  setup: "apt-get update && apt-get install -y build-essential"
  install: "npm install"
  start: "npx tsx src/index.ts"
```

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.

{/* There is a special setup required for bundling workers for distribution in the iii registry at */}

{/* workers](./workers-registry#bundle-workers-targz-archives). */} {/* </Note> */}

### `setup`

Runs once when the sandbox is provisioned. Use it for system-level packages your dependencies need
to build.

<CodeGroup>
  ```yaml Node theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
  scripts:
    setup: "apt-get update && apt-get install -y build-essential"
  ```

  ```yaml Python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
  scripts:
    setup: "apt-get update && apt-get install -y libpq-dev"
  ```

  ```yaml Rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
  scripts:
    setup: "apt-get update && apt-get install -y pkg-config libssl-dev"
  ```
</CodeGroup>

### `install`

Installs dependencies.

<CodeGroup>
  ```yaml Node theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
  scripts:
    install: "npm install"
  ```

  ```yaml Python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
  scripts:
    install: "pip install watchfiles && pip install -e ."
  ```

  ```yaml Rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
  scripts:
    install: "cargo install cargo-watch && cargo build"
  ```
</CodeGroup>

### `start`

Starts the worker process.

<CodeGroup>
  ```yaml Node theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
  scripts:
    start: "npx tsx watch src/index.ts"
  ```

  ```yaml Python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
  scripts:
    start: "watchfiles 'python main.py'"
  ```

  ```yaml Rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
  scripts:
    start: "cargo watch -x run"
  ```
</CodeGroup>

## `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.

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
env:
  LOG_LEVEL: info
  MY_API_KEY: replace-me
```

## `dependencies`

Map of `<worker-name>: <semver range>` declaring other workers this worker depends on, resolved
against the registry.

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
dependencies:
  http: "^0.20"
  state: "^0.20"
```

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.

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
resources:
  cpus: 2
  memory: 2048
```

### `cpus`

Optional integer. Number of vCPUs. Defaults to `2`, capped at `4`.

### `memory`

Optional integer. Memory in MiB. Defaults to `2048`, capped at `4096`.

## Publish metadata: `iii`, `deploy`, `manifest`, `tags`

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 local
`iii worker add`) but never reads them at runtime.

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii: v1 # manifest format marker
deploy: image # release artifact type: binary | image | bundle
manifest: pyproject.toml # file the release version is read from
tags: # search aliases sent to the workers registry
  - http
  - rest
  - api
```

`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.