handlers.toml

TaskDaemon handlers.toml guide

handlers.toml

Each [handlers.name] section maps the submitted task type to a Docker image and a pool of reusable handler processes.

[handlers.echo]
image = "my-echo-handler:latest"
instances = 2

[handlers.resize]
image = "image-processor:latest"
instances = 4
timeout = 60
memory_limit = "512m"
handler_selection = "round-robin"

[handlers.resize.env]
LOG_LEVEL = "info"

Handler Options

Option	Type	Default	Description
image	string	required	Image available to the Docker engine used by TaskDaemon
instances	integer	2	Number of reusable handler processes in this pool
timeout	integer	daemon timeout, normally 30	Execution timeout in seconds; overrides DAEMON_TASK_TIMEOUT
memory_limit	string	unset	Docker memory limit, for example 512m
env	table of strings	empty	Environment variables passed to each handler container
handler_selection	string	round-robin	round-robin, first-available, or random

Pool size and worker count control different resources. Workers claim tasks; a handler pool limits simultaneous executions for that task type. Adding workers beyond available handler instances can increase waiting without improving throughput. Measure your workload before raising either setting.

Shared Images

Multiple task types may use the same image with separate pools:

[handlers.resize]
image = "image-handler:latest"
instances = 4

[handlers.thumbnail]
image = "image-handler:latest"
instances = 2

The request’s top-level task_type lets the handler choose the operation.

Startup and Warmup

Build or pull all configured images before starting TaskDaemon. Startup launches persistent Docker clients for the configured pools. There is no handler readiness handshake: initialization may still be running when the first task arrives, and that task’s timeout includes this wait. Use a representative smoke task to check each handler after deployment. /health checks daemon and queue health; it does not confirm that each handler is ready.

File Location

The CLI uses --config when supplied, otherwise HANDLER_CONFIG, otherwise handlers.toml in its current directory. The supplied Docker image sets HANDLER_CONFIG=/app/handlers.toml; mount your file there read-only.

See environment configuration for retry policy, batch size, leases, and queue selection.