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

# handlers.toml

> Configure task handlers and container pools

# handlers.toml

Configure task handlers in `handlers.toml`. Each handler defines a Docker image and pool settings.

## Basic Configuration

```toml theme={null}
[handlers.echo]
image = "my-echo-handler:latest"

[handlers.resize]
image = "image-processor:latest"
instances = 4
timeout = 30
handler_selection = "round-robin"
```

## Handler Options

| Option              | Type   | Default       | Description                                                          |
| ------------------- | ------ | ------------- | -------------------------------------------------------------------- |
| `image`             | string | required      | Docker image name                                                    |
| `instances`         | number | 2             | Number of container instances to pre-warm                            |
| `timeout`           | number | 30            | Task timeout in seconds                                              |
| `handler_selection` | string | `round-robin` | How to select containers: `round-robin`, `first-available`, `random` |
| `memory_limit`      | string | none          | Container memory limit (e.g., `512m`, `1g`)                          |
| `env`               | table  | none          | Environment variables for the container                              |

## Examples

### Minimal

```toml theme={null}
[handlers.process]
image = "my-handler:latest"
```

### Full Configuration

```toml theme={null}
[handlers.ml-inference]
image = "ml-model:latest"
instances = 4
timeout = 60
handler_selection = "first-available"  # Maximize cache hits
memory_limit = "2g"
env = { MODEL_PATH = "/models/v2", DEBUG = "false" }
```

### Multiple Handlers

```toml theme={null}
[handlers.resize]
image = "image-handler:latest"
instances = 4
timeout = 30
handler_selection = "round-robin"

[handlers.thumbnail]
image = "image-handler:latest"
instances = 2
timeout = 15
handler_selection = "round-robin"

[handlers.wordcount]
image = "text-handler:latest"
instances = 2
timeout = 10
handler_selection = "first-available"
```

## Handler Selection Strategies

<Tabs>
  <Tab title="round-robin">
    Cycles through containers sequentially for even distribution.

    ```toml theme={null}
    handler_selection = "round-robin"
    ```

    **Best for:** General workloads, stateless handlers
  </Tab>

  <Tab title="first-available">
    Always tries slot 0 first, maximizing container reuse.

    ```toml theme={null}
    handler_selection = "first-available"
    ```

    **Best for:** Handlers with warm caches, ML models
  </Tab>

  <Tab title="random">
    Starts from a random slot each time.

    ```toml theme={null}
    handler_selection = "random"
    ```

    **Best for:** Very high concurrency scenarios
  </Tab>
</Tabs>

See [Handler Selection Strategies](/configuration/handler-selection) for details.

## Container Pooling

The `instances` setting controls how many containers are pre-warmed at startup:

```toml theme={null}
[handlers.cpu_intensive]
image = "heavy-processor:latest"
instances = 8  # More instances for high throughput
timeout = 60

[handlers.quick_task]
image = "fast-handler:latest"
instances = 2  # Fewer instances for light tasks
timeout = 5
```

<Tip>
  Set `instances` based on expected concurrency. More instances = higher throughput but more memory usage.
</Tip>

## Environment Variables

Pass environment variables to handler containers:

```toml theme={null}
[handlers.api-caller]
image = "api-handler:latest"
instances = 4
env = { API_KEY = "secret", API_URL = "https://api.example.com" }
```

## Memory Limits

Restrict container memory usage:

```toml theme={null}
[handlers.memory-heavy]
image = "data-processor:latest"
instances = 2
memory_limit = "1g"
```

## File Location

TaskDaemon looks for the config file in this order:

1. `--config` CLI argument
2. `HANDLER_CONFIG` environment variable
3. `handlers.toml` in current directory
4. `/app/handlers.toml` (Docker default)

```bash theme={null}
# CLI
./task-daemon --config /path/to/handlers.toml

# Environment
HANDLER_CONFIG=/path/to/handlers.toml ./task-daemon

# Docker
docker run -v ./handlers.toml:/app/handlers.toml mshelia/taskdaemon
```