> ## 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:
  iii-http: "^0.20"
  iii-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`.