# How a run works

What happens when Borago Board runs a task, what you see at each point, how a run ends, and what you can do when it fails or stalls.

A run is one attempt by an AI model to do a task inside your project's container. It starts when the queue or a person starts the task and ends when the board records the outcome on the card. Every run starts fresh. There is no session resume, so a run knows about earlier runs only through what is on the task, such as its comments and the summary of the last run.

Every provider works the same way from your side. Claude, OpenAI, Gemini and Grok run on your own API key, and self-hosted models run on a server you add under Settings. The table at the end lists what differs between them.

## Starting a run

A run starts in one of two ways. The project's queue picks the next To Do task (the order is on [the queue and its holds](/docs/reference/queue-and-holds/)), or you press **Run with** followed by the provider's name on a To Do task. **Continue with** on a Blocked task and **Run again with** on a Done task start a retry, which also gives the model the previous run's output.

One task runs at a time per project, because every task in a project shares one container. Pressing run while another task in the project is running queues the task instead.

The card moves to **In Progress** and shows a timer. The timer is kept with the task, so a reload, another browser or your phone shows the same elapsed time as the desktop.

## What is checked first

Before any model is called, the board checks that the run can work.

| Check | If it fails |
|---|---|
| The project has a container, and it is running | The task is Blocked with a comment saying to start the container and retry, and a notification is raised |
| The project has a key for its provider, and the provider accepts it | The task is Blocked with a comment pointing to the project's **AI Auth** tab, or the queue pauses until the credential is fixed on that tab. A self-hosted service needs no key |
| With container management on, the container can reach the board through the host firewall | The queue pauses and the banner names the firewall rule to allow. See [the firewall page](/docs/firewall/) |

## During the run

The model works inside the project's container. It can run commands in a shell, read and edit files, search the repository, propose new tasks, and on most providers search the web and read web pages. [What the agent can do](/features/agent/) describes each tool.

The output streams into the task window as it is written, and is saved to the task as it goes, so closing the window loses nothing. A card whose run has written nothing for 5 minutes shows a hung warning.

Limits you may meet:

| Limit | Value | What happens |
|---|---|---|
| One command with no output | 5 minutes | The command is stopped and the model is told to run it in the background instead |
| One command in total | 15 minutes | The same |
| The whole run with no output | 10 minutes, or 20 minutes on a self-hosted model | The run ends and the task is Blocked with a comment. A foreground command that never returned is the usual cause |
| A self-hosted run in total | 120 minutes unless the service sets another **Time limit per task (min)** | The run ends |
| Web searches per run | 8 | Further searches are refused |
| Web pages read per run | 5 | Further reads are refused |
| The project's cost budget | Set in **AI Auth** per provider | The queue stops starting new runs once this machine's estimated spend reaches it. The run in progress finishes |

The prompt never contains an environment variable's value. The values are available inside the container when a command runs, so a command that prints one shows it to the model. What the board stores and shows of the output has the values the run was given replaced by `[redacted:NAME]`, except a very short value or one the agent transformed first.

## How a run ends

A run ends by saying what happened. The board turns that into what you see on the card.

| Outcome | What you see |
|---|---|
| Done | The card moves to **Done** with a short summary comment |
| Blocked | The card moves to **Blocked** with the reason, and a notification is raised |
| A question | A question comment with buttons for the options, and a free-text field where allowed. The card waits in **In Progress** while the task window is open, or moves to **Blocked** otherwise. Answering all questions sends the task back to To Do, and the next run sees your answers. [When the agent asks a question or needs you](/docs/guides/questions-and-actions/) |
| A wait | The model asked to wait for something, such as a long build. The card stays In Progress, the board checks for it periodically, and the task runs again when it is ready or the wait times out. Nothing else runs in that project meanwhile |
| A reply | When the task asked for an answer rather than a change, the answer is kept as a **Reply** comment |
| Steps for you | Things only a person can do, such as approving access. They appear as an action comment, a marker on the card and a notification |
| New tasks | Proposed follow-up tasks are created in **Planning** and linked to the task that proposed them, then moved to To Do unless they need you first. At most 8 per run and 20 in one family. |
| Files | Files the run named are attached to the task |
| Tools installed | Tools the run reported installing are added to the project's Dockerfile, and a notification offers a restart so they survive the next rebuild. An install the run did not report is rewritten for build time and added as lines the next build tries. When it cannot be rewritten, the commands arrive in an action comment instead |

If a run stops without saying Done or Blocked, usually because the model meant to continue, the card still lands in **Done**. It carries an action comment and a notification asking you to check the output, and the history says the outcome was not declared by the run.

## After a run

- **Review.** With **Review the result after a run** on in the project's **AI Roles** tab, a second model checks the finished work against the task. A negative verdict leaves an action comment and a notification. It never changes the task's column or runs it again. It is off by default because it costs a call on every run.
- **Pull request link.** For a project connected to GitHub, GitLab, Bitbucket or Gitea, a run that committed or switched branch gets a link to open a pull request, or a merge request on GitLab. The board does not open it for you. [Connecting a repository](/docs/guides/connecting-a-repository/)
- **Hooks.** Scripts and flows set to run when a task reaches Done or Blocked start on the desktop. [Flows](/docs/guides/flows/)
- **Run history.** Every run's output is kept on the task, up to 100 runs, with its outcome and the model that ran it.
- **Export.** The copy and download buttons at the top of the task dialog turn the task into one Markdown document with its description, every comment and the last run, with its outcome, AI, duration and output. Earlier runs are left out.

## When a run fails

Temporary problems, such as a provider outage or an error the board does not recognise, send the task back to To Do to try again after 1, 3, 5, 10 and 30 seconds. After 6 failures in a row the task is Blocked and the project's queue pauses until you resume it. A retry sees what the previous attempt did.

A rate limit does not count as a failure. The task goes back to To Do and the queue waits until the provider says the limit resets.

Some failures block the task straight away, because trying again cannot fix them. A missing container, exhausted provider credits, a model your key cannot use, a request the provider rejects, and a stalled run. When a provider cannot be reached repeatedly, the comment says whether the provider reports an incident, and suggests restarting the project's container when it does not.

Pressing a run button or dragging the task to To Do or Planning resets the failure count.

## Stopping a run

**Stop** on an In Progress task, after a confirm, ends the run and any command it was running. The task moves to **Planning**. A running card cannot be dragged. Dragging it opens the same confirm. Stop also works from a browser or your phone while the desktop is connected.

## If the app quits during a run

A run cannot outlive the app. When the desktop quits or crashes, the next start puts every interrupted task back in To Do with a note in its history, and the queue runs it again from the start. A task that was waiting on your answer to a question is left as it was. With cloud sync on, a task running on your other desktop is left alone.

## Where the providers differ

| | Claude | OpenAI | Grok | Gemini | Self-hosted |
|---|---|---|---|---|---|
| Credential | API key | API key | API key | API key | A server address, and a token only if the server needs one |
| Web search | Yes | Yes | No | Yes, on Gemini 3 and newer | No |
| Reading web pages | Yes | No | No | Yes, on Gemini 3 and newer | No |
| Investigator | Yes | Yes | Yes | Yes | No |
| **Enhanced accuracy mode** | Raises the reasoning effort | Raises the reasoning effort | Raises it on models that support it | Raises the reasoning effort | No effect |
| Cost | Estimated from the provider's list prices | Estimated from list prices | Estimated from list prices | Estimated from list prices | None. A time limit per run takes the budget's place |
| Cost budget | Per provider, this machine | Per provider, this machine | Per provider, this machine | Per provider, this machine | None |
| Stall limit | 10 minutes | 10 minutes | 10 minutes | 10 minutes | 20 minutes |

The cost shown is an estimate. The provider's invoice is the final figure. [Cost and usage](/docs/guides/cost-and-usage/)

Related: [The queue and its holds](/docs/reference/queue-and-holds/), [What the agent can do](/features/agent/), [States](/docs/reference/states/), [Limits and defaults](/docs/reference/limits-and-defaults/), [Writing tasks the agent can do](/docs/guides/writing-tasks/).