Skip to Content
ConceptsRuns

Runs

Hand an agent a task and come back to the result. A run is one agent task, done from start to finish in its own fresh space. The agent works on its own and asks you when it needs a decision. Walk away mid-question: Marshal parks the run, frees its compute, and picks up the same conversation the moment you answer.

Available when your administrator enables runs.

What you can do with it

  • Fix a flaky test. “Find out why checkout.spec.ts fails one time in ten, fix it, and open a pull request.” Follow along on the run page, or close the tab and read the result later.
  • Triage a backlog. Start a run with “Label and summarize the 40 open issues in web-app.” Tell it to ask you before it closes anything, and answer its questions from Home or Slack.
  • Work from your AI client. Your assistant starts a run through MCP, the run does the heavy work in its own space, and your assistant follows it and reads the result.

See it end to end: Review every pull request and Delegate from your AI client.

How it fits

  • A run needs a task and a manifest you are allowed to use. The manifest decides the agent, the tools and the credentials.
  • Each run gets a fresh space, frozen to what the manifest said at launch. The run keeps a full record: transcript, changes and cost. The record stays after the space is gone.
  • You start a plain run yourself: from the web (“Ad-hoc run”), the CLI, an AI client through the Marshal MCP server, or the API. A deputy starts runs from its missions: by hand, on a schedule, or on an event.
  • Questions from a run reach the right person on Home and in Slack.

Lifecycle

While a run works, it can wait on a person and pick up again:

Every run ends in one of four final states:

You seeStatusMeaning
pendingpendingThe run exists. Its space is starting.
runningrunningThe agent is working.
Waiting on you, or awaiting humanawaiting_humanThe agent asked a question. The badge names who it waits on.
ParkedparkedNobody answered in time. The space is shut down to save cost, and the question stays open.
engagedengagedA person has taken over the space.
succeededsucceededThe run finished.
failedfailedThe run hit an error.
timed outtimed_outThe time budget ran out.
canceledcanceledA person canceled it.
Needs inputa final statusThe run ended because a question was never answered. Continue it to carry on with your answer.
Ended, not finisheda final statusThe agent stopped without saying it was done, and the run ended. Continue it to pick up where it stopped.

The three human-wait states (awaiting human, parked, engaged) pause the timeout clock. The run’s budget counts only the time the agent works. A run gets 15 minutes unless you set another budget, and no run lasts more than 24 hours in total, including waiting.

A run never ends silently while a person is needed. If the agent reached out and then stopped, the run is held open with the question “This run stopped without asking anyone. Continue it, or is it done?”

A deputy’s run ends when its agent says it is done. If the agent stops without saying so, Marshal resumes it with a note to carry on or finish, up to twice, and each nudge shows in the run’s timeline. If it still stops, the run goes to sleep and you are asked whether to continue it, mark it done, or end it. Marking it done ends the run as succeeded. Ending it, or letting the question expire, records the run as Ended, not finished. On the Runs page, filter to that outcome to find every run that stopped early. Deputy insights count these runs in their own bucket.

Steer a live run

  • Message it. Send a note while it works to add context or change course.
  • Take over. The agent pauses and you get a shell in its space. Hand it back when you are done.
  • Continue. After a run ends, Continue run starts a new run with the same conversation and, when available, a copy of the working tree.

Owners and admins see every run in the organization. Members see the runs they started and the runs of deputies they can see.

SpacesDeputies