Start and track runs
Hand an agent a task from your terminal, a deputy, a schedule or your own AI client, and find every result in one list. Each run works in its own fresh space with a time budget, and Marshal keeps its full record after the environment is gone. For what a run is and its statuses, see Runs. To follow one run live, see The run page.
Available when your administrator enables runs.
What you can do with it
- Kick off work and walk away. Start a test-fix run from your terminal with
--follow, close the laptop, and read the result on the run page later. - Script it in CI.
marshal run --followexits non-zero unless the run succeeds, so a CI job can start a run and fail the build when the agent fails. - Find last night’s runs. Open Runs, pick Yesterday and the deputy, and filter by status to see which nightly runs need you.
See it end to end: Review every pull request and Nightly dependency upgrades.
How you start a run
| Way | How |
|---|---|
| CLI | marshal run --manifest <id-or-name> --task "<prompt>". In the web it shows as “Ad-hoc run”. |
| Deputy mission | Launch on a deputy’s page, or marshal deputies launch <slug> --mission <mission>. See Deputies. |
| Schedule or event | A deputy mission starts itself. See Schedules and triggers. |
| Your AI client | The runs_launch tool of the Marshal MCP server. |
| API | POST /api/runs |
| A finished run | Continue on its page. See The run page. |
To start a run you need the right to use the manifest.
marshal run options
| Option | Meaning |
|---|---|
--manifest | Manifest id or name. Required. |
--task | The prompt. Required. |
--runtime | The agent runtime. The default is claude-code. |
--compute-class | A size name such as medium, or a compute class id. See Choosing a size from the CLI. |
--title | A short name for the Runs list. By default Marshal uses the first line of the task. |
--timeout | The time budget. The default is 15 minutes. See Timeouts and parking. |
--follow | Stream the transcript until the run ends. Exits non-zero unless the run succeeds. |
--keep-on-failure | Keep the run’s space up for 24 hours if the run fails, so you can attach and look. |
The Runs list
Runs shows every run you can see, newest first, for the last 24 hours. Switch the window to last hour, today, yesterday, last 7 days, last 30 days or any time.
Filter by deputy, mission, status (several at once), how it was triggered, and dates, or search the task, run id, deputy and mission. Filters are saved in the URL, so you can bookmark or share a view. You can group chains of continued runs, and include launches that wait in a queue. A waiting launch shows the title its caller gave it.
Who launched a run, and who owns it
Every run page shows launched by and owner. Launched by is the person who started the run from the web app, the CLI, an API token or an MCP client. Owner is the person, team or organization the run is accountable to. When both are the same person, you see one name.
Runs started by a schedule, a webhook or a deputy’s launch queue have no launching person. They show how they were triggered and the owner of the deputy at the moment the run started. A run started by an orchestrating run shows the same launcher and owner as its parent.
Names and emails are recorded when the run starts, so they stay correct if someone is renamed or leaves. A person who has left shows with a “removed” mark. marshal runs get prints the same line, and runs_get and runs_list in MCP return launched_by and owner.
In the CLI
| Command | What it does |
|---|---|
marshal runs list | Run id, status, runtime, the run’s title cut to 50 characters, and who launched it. Waiting launches show with a ql_ id, their title when the caller gave one, and why they wait. |
marshal runs get <run-id> | Id, status, runtime, space, task, who launched it and who owns it, reason, output and error. |
marshal runs logs <run-id> | Stream the transcript until the run ends, through any park and resume. Exits non-zero unless the final run succeeded. |
marshal runs cancel <run-id> | Cancel a run, or a waiting launch by its ql_ id. |
marshal runs timeout <run-id> --add 15m | Add time, or --pause and --resume the timeout. |
marshal deputies message <run-id> <text> | Send a message to a live run. The agent reads it on its next turn, or at once with --interrupt. |
Who can see and act on a run
| Action | Who |
|---|---|
| See a run | Org owners and admins see every run. Other members see runs they started, runs of org deputies, runs of deputies they own, and runs of team deputies for teams they are on. |
| Cancel a run, change its timeout | Anyone who can see it |
| Rename, Continue, Take over | Whoever may act on the run: the person who started an ad-hoc run, or the deputy’s owner scope for a deputy run |
| Answer its question | The people asked, and org owners and admins |
See Roles and permissions for the full list.
Edge cases
- A run that never gets its environment up within 15 minutes ends as failed. See Timeouts and parking.
- A launch over a mission’s concurrency limit waits in a queue and starts by itself. See Deputies.
- A run you may not see answers “not found”.
Try it
marshal run --manifest <your-manifest> --task "Find and fix one failing test" --followThen open Runs in the web and select your run.