Concurrency controls limit how many pipeline runs execute at once, at both the pipeline and organization level. Two agents fighting over the same database connection pool or sandbox quota is slower than running them one at a time, and more expensive. Farna Control enforces limits before a run starts, so a run gets a slot or waits for one to free up.

In short

max_concurrent_runs caps how many runs one pipeline executes at once. An org-level sandbox cap limits total concurrent work across all pipelines.
Use it for pipelines that call expensive LLMs, provision sandboxes, or hit shared infrastructure like Postgres and Redis.
Skip it for read-only or lightweight pipelines where a concurrent run costs little.
Runs that exceed the cap queue instead of failing and start when a slot opens.

The problem it solves

Three pipelines call the same model backend and write to the same Postgres database, each with no limit. On a quiet day two start together and the third follows a minute later. The connection pool saturates, two runs succeed, and the third times out with a lock error and retries, burning more model tokens. The next day five run at once: two fail, and the retry storm pushes model spend up 30% overnight. The root cause is a missing ceiling on concurrent runs. Without one, the system starts as many jobs as it can, not as many as the infrastructure can sustain.

How it works

Farna Control enforces concurrency at two layers: the product layer controls what users see, and the infrastructure layer controls what the deployment can handle.

Every pipeline has a max_concurrent_runs field, default 1 (one run at a time). Raise it to process work in parallel or allow overlapping runs without waiting for the previous one to finish.

{
  "name": "summarize-docs",
  "max_concurrent_runs": 3
}

The executor enforces the limit via a database lock (SELECT FOR UPDATE on the pipeline row), so two runs cannot slip past the check at once. When a run starts and no slot is available, the system checks whether one frees up within lock_wait_timeout_seconds. If so, the run is deferred and starts when a slot opens. If not, it fails cleanly with error_code="lock_timeout" instead of consuming resources it cannot use. Queued runs act as a buffer, smoothing out bursts without overloading the system.

An organization-wide sandbox cap limits total concurrent sandboxes across all pipelines. Even if every pipeline sets max_concurrent_runs: 5, the org cap keeps the total within what the deployment can handle.

Cron, webhook, and polling triggers respect both limits. A cron job that fires every 15 minutes will not start a new run when the pipeline is at capacity; it queues and starts when a slot opens, so scheduled work does not collide with manual or other triggered runs.

Journey example: before and after

Before

Jordan runs a data team at a mid-size SaaS company with four pipelines: customer feedback ingestion, support ticket summarization, weekly reports, and warehouse sync, all without limits. On Monday mornings the feedback ingestion and weekly report start together, fight for Postgres connections, and the report pipeline retries three times, burning model tokens. By Tuesday the team staggers runs 30 minutes apart by hand, which works until someone forgets.

After

Jordan sets max_concurrent_runs: 2 on the report pipeline and max_concurrent_runs: 3 on the feedback ingestion pipeline, with the org sandbox cap at 6. The report queues behind the ingestion instead of colliding: no retries, no wasted tokens, no manual staggering. Jordan checks the analytics dashboard weekly to confirm the queue is draining and adjusts limits as the team adds pipelines.

When to use it vs. when not to

Use concurrency limits on pipelines that call expensive resources: model backends with token-based pricing, sandboxes with per-use billing, or shared databases with connection pools, and on cron- or webhook-triggered pipelines where a burst can pile up faster than the infrastructure can handle. A lightweight pipeline that reads a file and returns a summary needs no limit when it completes in under a second and touches no shared resources. Match limits to each pipeline's actual cost and shared-resource use rather than setting one blanket limit.

Where it fits in a pipeline

Concurrency controls sit alongside governance gates and the audit trail. Where HITL gates decide whether a step should proceed, concurrency controls decide whether the infrastructure can support it. Together they form the operating contract between what a pipeline wants to do and what the deployment can sustain. For the broader context, see the principles of Farna Control.

Go deeper

Read the concurrency docs for sizing formulas and infrastructure knobs, or the related docs on pipelines. Take the product tour to see concurrency controls in action, or use the contact page to talk to us about tuning concurrency for your deployment.