Skip to main content
Task Queues are durable distribution systems that route agent tasks to available workers. Queues hold work; workers (machines running the Kubiya worker process) connect to queues and pull tasks to execute. Use Kubiya Cloud queues to start quickly, then create custom queues when you need to scale execution across your own infrastructure, isolate workloads, or reach private network resources. Kubiya Platform Overview

​
When to use

  • Scale execution horizontally across many machines.
  • Isolate workloads by environment, team, region, or hardware (e.g., GPU vs. CPU).
  • Reach private resources by attaching self-hosted workers inside your network.
Task Queues vs Workers: A task queue is a waiting area for work. Workers are the execution engines that pull from queues and run agent workflows. Learn more about Workers.

​
What you’ll see in the Dashboard

  • KPI chips: Active Workers • Queues • Capacity • Last Updated.
  • Queue cards (one per queue):
    • Status (Active/Idle) and a capacity bar (e.g., 1 / 10 workers).
    • Connect Worker area with a ready-to-copy command.
    • Configure (edit name/description, control plane, max workers).
    • View workers attached to this queue.
  • New Queue: creates another queue and gives you a fresh connection command.

​
How it works

  1. A Control Plane defines what capabilities are available (Skills, MCP servers, LLM settings, policies).
  2. An Agent or Team receives a task to execute.
  3. The task is routed to a Task Queue based on environment, priority, or explicit routing rules.
  4. Workers connected to that queue pull the task and begin execution.
  5. The worker executes the agent workflow in an isolated environment with streaming logs and audit trails.
  6. Results stream back to the Control Plane and user.
Multiple workers can attach to the same queue for parallel execution and high availability. A single machine can also attach to multiple queues if it has capacity.

​
Create a new queue

Worker Queue Creation
  1. Click New Queue.
  2. Set a Queue Name and optional Display Name/Description. Tip: name by purpose, e.g., staging, gpu-tasks, prod-eu.
  3. Choose a Control Plane (Kubiya Cloud is the default, fully managed option).
  4. Set Max Workers (the max concurrent worker processes for this queue).
  5. Click Create Queue. You’ll get a Connect Worker command.

​
Add workers to a queue

Workers are managed through the Kubiya CLI. See the Workers page for a conceptual overview of what workers are and where they can run. Requirements: the target machine has Python 3 and the Kubiya CLI installed.
  1. On the queue card, open Connect Worker and copy the command.
  2. Run it on any machine you want to contribute capacity from. Example format: kubiya worker start --queue-id <QUEUE_ID>
  3. Repeat on more machines to scale out.
    • Each started worker process consumes one worker slot.
    • The same machine may join multiple queues if resources allow.

​
Good defaults & tips

  • Keep max workers modest at first; raise as your team’s throughput grows.
  • Use separate queues for boundaries (prod vs. staging, region, GPU, high-risk tasks).
  • Add a clear description so teammates know what belongs on the queue.
For worker concepts and lifecycle management, see Workers. For technical deployment details and advanced configurations, see Worker Management CLI.

​
Security & isolation

  • Steps execute in containers with the environment’s configured context, policies, and Skills.
  • For self-hosted workers, restrict the host’s access to only what the queue needs.
  • Rotate credentials and remove idle workers by stopping the worker process on that host.

​
Troubleshooting

  • Worker won’t connect: verify Python 3 + CLI are installed; re-copy the exact command; check outbound network access.
  • Jobs stuck in queue: ensure at least one online worker and that capacity isn’t zero.
  • “No capacity” warnings: increase Max Workers or attach more machines.
  • Slow runs: add more workers or split work across additional queues.