Creating Workers

<!-- generated by iii-skill-render. DO NOT EDIT (changes here are overwritten on the next render). Edit docs/next/creating-workers/worker-manifest.mdx. -->


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. Compose reads it when preparing a `path://` worker or a
registry package. Project workers are declared and operated through
[`worker-compose.yaml`](../using-iii/compose), not the engine's `config.yaml`.

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

{/* <Note> */}
{/* There is a special setup required for bundling workers for distribution in the iii registry at */}
{/* [workers.iii.dev](https://workers.iii.dev). See [Registry / Bundle */}
{/* 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
scripts:
  setup: "apt-get update && apt-get install -y build-essential"
```

```yaml Python
scripts:
  setup: "apt-get update && apt-get install -y libpq-dev"
```

```yaml Rust
scripts:
  setup: "apt-get update && apt-get install -y pkg-config libssl-dev"
```

</CodeGroup>

### `install`

Installs dependencies.

<CodeGroup>

```yaml Node
scripts:
  install: "npm install"
```

```yaml Python
scripts:
  install: "pip install watchfiles && pip install -e ."
```

```yaml Rust
scripts:
  install: "cargo install cargo-watch && cargo build"
```

</CodeGroup>

### `start`

Starts the worker process.

<CodeGroup>

```yaml Node
scripts:
  start: "npx tsx watch src/index.ts"
```

```yaml Python
scripts:
  start: "watchfiles 'python main.py'"
```

```yaml Rust
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
env:
  LOG_LEVEL: info
  MY_API_KEY: replace-me
```

For managed and reusable workers, configure the namespace in the compose file that deploys the
worker rather than baking it into the shipped worker. Set `III_NAMESPACE` in the worker service's
environment; the SDK reads it when no explicit `namespace` option is passed. `config.yaml` does not
support a per-worker `namespace:` key.

When registering a worker programmatically, you may instead pass `namespace` directly to
`registerWorker` / `register_worker`. The explicit option takes precedence over `III_NAMESPACE`.
When neither is set, the worker registers in the `default` namespace.

## `dependencies`

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

```yaml
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
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 a local Compose
worker) but never reads them at runtime.

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