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

[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

[handlers.process]
image = "my-handler:latest"

Full Configuration

[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

[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

round-robin

Cycles through containers sequentially for even distribution.

handler_selection = "round-robin"

Best for: General workloads, stateless handlers

first-available

Always tries slot 0 first, maximizing container reuse.

handler_selection = "first-available"

Best for: Handlers with warm caches, ML models

random

Starts from a random slot each time.

handler_selection = "random"

Best for: Very high concurrency scenarios

See Handler Selection Strategies for details.

Container Pooling

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

[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

Set instances based on expected concurrency. More instances = higher throughput but more memory usage.

Environment Variables

Pass environment variables to handler containers:

[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:

[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)

# 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