Timeouts and parking
Let agents work as long as the job needs, and never pay for a run that is only waiting for you. The timeout limits how long the agent may work. Parking shuts the environment down while a run waits for a person, so the wait uses no CPU or memory, and brings the run back the moment someone answers.
Available when your administrator enables runs.
What you can do with it
- Ask before merging, answer in the morning. A nightly deputy asks “Merge to main?” at 17:50. Nobody is around, so the run parks and uses no CPU or memory overnight. You answer from Slack at 09:00 and the run picks up where it stopped.
- Let a long refactor finish. You are watching a big migration and it is close to its time limit. Press Pause timeout in the header and the agent keeps working with no cut-off.
- Look before you decide. A parked run asks you to approve a schema change. Press Wake to look, read its diff and its preview, then answer.
See it end to end: Nightly dependency upgrades.
How it works
The timeout counts work time
The timeout starts when the run starts. Time spent waiting for a person is given back, so a run that waits four hours for an answer has not used four hours of its budget. When the budget runs out, the run ends as timed_out and its page says “It ran out of time”.
Every run also has a hard cap of 24 hours from its start, with pauses and waiting included.
A worked example
- 17:50, hot. The agent asks and waits. The run is
awaiting_human. Its environment stays up so an answer gets an instant reply. - 18:20, parked. Nobody answered within the hot window (30 minutes by default). Marshal stops the environment. The run is
parked, the question stays open, and the conversation and the changes are kept. - 09:00, resumed. You answer. Marshal starts a new segment of the same run with the budget that was left, and always at least 5 minutes so the agent has time to act. The agent gets your answer with a note that the run was parked.
If nobody answers within the park time limit (24 hours by default), the run ends as failed with the badge Needs input. The work did not go wrong. Continue the run and the continuation carries your answer. See The run page.
When a run stays hot instead of parking
A run waits with its environment up, rather than parking, when:
- it waits on a permission request, not on a question
- someone has taken it over
- Marshal could not start a new segment for it later, for example because the person it runs for has left the org
What you see on a parked run
- The status reads Parked. The question card in Needs you and the Slack message both say the run is parked and that answering resumes it.
- Changes, Audit and Costs stay open.
- The question has Wake to look.
The run page follows the chain. If you are watching a run that resumes, the page moves to the new segment.
Wake to look
Wake to look brings a parked run back so you can look at its work before you answer. The agent asks the same question again, and the page moves to the new segment. You can wake a run if you could answer its question. A run that was woken in the last 60 seconds can be woken again after that minute.
A run never ends silently
Marshal never lets a run end silently when someone might still need to look. If the agent finishes after reaching out to a person, Marshal holds the run open and asks: “This run stopped without asking anyone. Continue it, or is it done?” with the buttons Continue and It’s done.
How Marshal decides, in order
| Situation when the agent finishes | Result |
|---|---|
| A person is attached through Take over | The run ends. |
| The agent has its own open question | The run parks on that question. |
| The org, deputy or mission says “Let the run end” | The run ends. |
| The agent said the work is done | The run ends. |
| The agent sent a heads-up | The run parks and Marshal asks the person. |
| The agent asked and nobody answered | The run parks and Marshal asks the person. |
| None of the above | The run ends. |
Who is asked
The agent never picks who to ask. Marshal asks the deputy’s contacts, or the mission’s own contacts when it sets them. With no contacts, it asks the person who started the run, and scheduled and webhook runs ask the deputy’s owner. For a team or org deputy, this is the person who created it. Everyone asked is a member of the org.
Change the timeout of a live run
A live run shows a pill in the header with the time left, for example 12m left, or 12m left, on hold while paused. It turns to a warning color under 5 minutes and an error color under 1 minute. Press it to see Elapsed, Timeout and Time left, and to:
- Add time: +5m, +15m, +30m, +1h, or Custom for any whole number of minutes
- Pause timeout and Resume timeout: pause stops only the clock, and the agent keeps working
From the CLI, pass exactly one of --add, --pause and --resume:
marshal runs timeout <run-id> --add 15m
marshal runs timeout <run-id> --pause
marshal runs timeout <run-id> --resume--add must be at least 1 minute. The agent gets a short note at its next step that its time changed. Every change is recorded in the audit log.
When the timeout ends a run from the CLI
marshal run prints the time budget when the run starts, for example timeout 2h. If you follow the run and the budget ends it, the command tells you in one line and shows the budget the run had, added time included:
timed out (1h5m) — use --timeout, or marshal runs timeout --addmarshal runs get shows the same line for a run that ended that way. Pass --timeout on the next run, or add time to a live run with marshal runs timeout --add.
If a change is refused, see Help with runs and deputies.
Configure it
Per run
| Where | Default | Range |
|---|---|---|
marshal run --timeout | The org’s Default time budget, else 15 minutes | Up to the 24 hour cap |
| A deputy’s Budget, or a mission’s time budget | The org’s Default time budget | 1 minute to 24 hours |
| Time budget for this run in a deputy’s launch dialog | The mission’s, then the deputy’s budget | 1 minute to 24 hours |
For the org
Org owners and admins set these under Settings > Deputies.
| Setting | Default | Range | What it controls |
|---|---|---|---|
| Default time budget | 15 minutes | 1 minute to 24 hours | The budget for any run that starts without a timeout of its own: a deputy run when neither the deputy nor the mission sets one, and a run started from the CLI, the API or an agent through the Marshal MCP. Runs already working keep the budget they started with. |
| Pod stays up while waiting | 30 minutes | 1 minute to 4 hours | The hot window: how long a waiting run keeps its environment up before it parks. |
| Question stays answerable for | 24 hours | 10 minutes to 7 days | The park time limit. It must be longer than the hot window. |
| When the run ends without an answer | Platform default (wait for the answer) | Wait for the answer or Let the run end | Whether a run that reached out to someone may end before they answer. |
The last three are in the When a run needs a person group. A mission, a deputy or a single question can set its own values. The most specific one wins: the question, then the mission, then the deputy, then the org, then the default.
Who can do what
- Anyone who can see a run can add time, pause and resume its timeout.
- The people asked can answer and wake the run. Org owners and admins can answer any question.
Limits and edge cases
- A run that is still
pendingafter 15 minutes ends as failed with “Its environment never finished starting”. A pending run is not timed out on its work budget. - A run has one open question at a time.
- A run can ask at most 20 questions per segment and 60 across a chain of segments, and send at most 60 heads-up notices per segment.
- Free-text answers longer than 16 KB are cut for the agent.
- A question needs someone to ask. If nobody can be asked, the question is refused.
- To take over a parked run, wake it first.
Try it
marshal run --manifest <your-manifest> --task "Ask me before you change any file, then make the change" --followLeave the question unanswered past the hot window, watch the run park, then answer it from Home.
Your terminal stays with the run the whole way. When the run parks, --follow prints that it is parked and keeps waiting. When you answer, it streams the run that carries the work on, and exits with that run’s result: zero when it succeeds, non-zero otherwise. marshal runs logs <run-id> follows a parked run the same way.