Dispatching runs

Dispatching hands a task to Devboxes; a runner picks it up as soon as one can serve your model's provider. This page covers what dispatch checks before it accepts the run, how a runner claims it, and why a run sits in Queued instead of failing.

Dispatch a run

Agent sessions → Dispatch run creates a run from a project, blueprint, branch, task prompt, priority, and model. The model picker shows the Devboxes catalog entries your organization can serve and links to credential management. The full catalog comes from the API's bundled Models.dev snapshot; models marked deprecated upstream are excluded from dispatch. Devboxes rejects unavailable and unknown model ids before they reach the queue. The Devboxes CLI and a Slack mention create the same runs through the same checks; when they omit a model, Devboxes chooses the first available catalog entry.

Before it enqueues, dispatch validates the model, the project's repository credential, environment snapshot, runner image, base branch, and blueprint. It rechecks provider capacity immediately before creating the run. If a credential or local runner becomes ineligible during the request, dispatch returns setup guidance without creating a run. Any failure surfaces directly in the dialog.

How the run finds a runner

The queued task waits for a runner to claim it. Claiming rechecks provider capacity:

• A local runner advertises the providers it can serve on its own machine — its device credential store plus saved auth-file references — with every claim request.
• The usable organization credentials — synced from a local runner, or connected/pasted on the Model providers tab — qualify every runner on top of that. A task whose provider matches one is claimable by dashboard-managed and local runners alike, and runs with the credential served from the dashboard. Dashboard-managed runners claim on organization credentials only. A credential marked Reconnect needed or Invalid does not qualify a claim.

Tasks are handed out in priority order (urgent → high → normal → low), oldest first within a priority, and only once the project's runner image build has completed.

What "Queued" means

Dispatch accepts only a model with a currently available provider. If that availability disappears before claim, the accepted run stays Queued until a matching runner returns instead of burning an attempt without a key.

Open Queue to see work across the organization. Attention contains blocked, failed, and review-ready runs; Active contains queued and running runs; All also includes settled work. Each tab shows its count and opens the same run detail used elsewhere in the dashboard.

If a run seems stuck in Queued, check in this order:

1. Is a runner online? Your machine must be running devboxes listen, or the organization must have a dashboard-managed runner.
2. Can any runner serve the model's provider? Check devboxes credentials status on your machine and the Model providers tab in the dashboard. A usable organization credential qualifies every runner, local runners included; a dashboard-managed runner needs the provider on the Model providers tab.
3. Is the project's runner image built? New projects build an image before their first run can be claimed.

Execution and retries

Once claimed, the task runs under a lease that the claiming runner refreshes while the container is alive. Launch failures requeue with backoff and are retried up to 3 attempts in total; after that the run fails with the last error. A running container that dies before reporting is detected and reported as failed, which consumes an attempt the same way.

Cancel a run

Every run that has not finished carries a Cancel run action — on its row in the Runs list and in the detail's action bar — behind a confirm dialog. Any member of the organization can cancel; dispatching needs an owner or admin, stopping a run does not.

What happens depends on whether a runner already claimed the run:

A requested cancellation sticks: it survives launch retries, and if the runner disappears the run still ends as Cancelled once its lease lapses. Cancelled is terminal — the run is never retried. To run the same work again, use Rerun on the run's agent session.

Next: Agent sessions — watching, steering, and reviewing the run you dispatched.