Skip to main content
Queues move work out of public requests. Use them for emails, webhook retries, image processing, cleanup, and other tasks that can run after the response.

​
Queue flow

1

Enable and create queues

Set [capabilities].queue = true in tovuk.toml, then run tovuk deploy --dry-run --json so the agent can confirm Queue meters, limits, and required fixes before provisioning resources. Create the dead-letter queue before the primary queue when failed work needs a separate recovery path.
2

Produce work

Send one job with tovuk queue send, send batches with tovuk queue send-batch, or use the same Queue API routes from the dashboard. Add --delay-seconds when work should wait before it becomes visible to the consumer.
3

Consume in Rust

Read TOVUK_QUEUE_JOBS from the runtime environment for the example queue, then handle queue deliveries in the Rust worker at POST /.tovuk/queues/<queue>. Return 2xx only after the batch has been handled safely.
4

Inspect and tune

Read Queue messages and metrics after deploy, then use tovuk service show service_1 --json to verify queues, usage, limits, and next actions. Tune retries, retention, batch size, batch timeout, and dead-letter settings with tovuk queue update.

​
CLI workflow

tovuk queue create --service service_1 failed_jobs --json
tovuk queue create --service service_1 jobs --max-batch-size 10 --max-batch-timeout-seconds 5 --dead-letter-queue failed_jobs --json
tovuk queue send --service service_1 jobs '{"kind":"welcome","user_id":"user_1"}' --json
tovuk queue send-batch --service service_1 jobs '[{"body":"{\"kind\":\"welcome\"}"},{"body":"{\"kind\":\"index\"}"}]' --json
tovuk queue messages --service service_1 jobs --json
tovuk queue metrics --service service_1 jobs --json
tovuk queue update --service service_1 jobs --max-retries 5 --json
tovuk queue update --service service_1 jobs --clear-dead-letter-queue --json
tovuk queue delete --service service_1 jobs --json

​
Dashboard

Dashboard Queue controls are available at https://tovuk.com/account/resources and https://tovuk.com/<handle>/resources. The Resources view can read recent Queue messages, read Queue metrics, send one Queue message, and send one Queue batch through the same metered Queue API routes as the CLI. It can also update Queue retries, retention, batch size, batch timeout, and dead-letter Queue settings. The dashboard uses these Queue API routes:
  • PUT /v1/services/{service_id}/queues/{queue}
  • GET /v1/services/{service_id}/queues/{queue}/messages
  • GET /v1/services/{service_id}/queues/{queue}/metrics
  • POST /v1/services/{service_id}/queues/{queue}/messages
  • POST /v1/services/{service_id}/queues/{queue}/messages/batch

​
API

  • POST /v1/services/{service_id}/queues
  • PUT /v1/services/{service_id}/queues/{queue}
  • GET /v1/services/{service_id}/queues/{queue}/messages
  • POST /v1/services/{service_id}/queues/{queue}/messages
  • GET /v1/services/{service_id}/queues/{queue}/metrics
  • POST /v1/services/{service_id}/queues/{queue}/messages/batch
  • DELETE /v1/services/{service_id}/queues/{queue}
Queue consumers are Rust worker routes at POST /.tovuk/queues/<queue>. Public traffic to /.tovuk/* is blocked.

​
Meters and caps

Queue usage is metered as queue_operations. 
tovuk limits set queue_operations --period month --value 1000000 --notify-at-percent 80 --json

​
Limits

  • Queue messages are capped at 128 KB total.
  • Send batches accept up to 100 messages and must fit 256 KB.
  • Consumer batches can process up to 100 messages.
  • Batch waits can be configured up to 60 seconds.
  • Visibility timeouts can be configured up to 12 hours.
  • Send delays can be configured up to 24 hours.
  • Consumer handlers have a 15 minute wall-clock limit.
Last modified on June 3, 2026