Deputies

Set up a standing worker once, and let it do the job again and again. A deputy has missions (saved prompts), a manifest, an owner and its own memory. A person, a schedule or a webhook event starts a mission, and each time the deputy starts a run that you can follow, message, take over and continue. For how deputies fit with runs, see Deputies.

Available when your administrator enables deputies.

What you can do with it

• PR reviewer. A team deputy with a “Review PR” mission and an event trigger on GitHub pull_request.opened. Every new pull request gets one review run, and the team lead owns the rules.
• Weekly dependency bump. A personal deputy with a schedule every Monday at 07:00 in your time zone. It opens one pull request per outdated package and asks you before it merges anything.
• Invoice checker. An org deputy with an event trigger on a custom webhook from your billing system, with the condition event.amount > 1000. Large invoices get a check run, and finance gets the question when something looks wrong.

See it end to end: Review every pull request and Nightly dependency upgrades.

How it works

• A mission is a named job on the deputy: a prompt with inputs, a run title and a time budget.
• Every start creates a run in a fresh space. The run works in the deputy’s manifest and acts as the deputy, never as the person or the event that started it.
• A run can reach what the deputy’s manifest gives it. Choose the manifest and its credentials to match the job.
• The deputy keeps its own context and memory. No person’s own context or memory reaches its runs.

Create a deputy

Open Deputies and press New deputy.

Marshal makes a slug from the name. The slug is the stable id in URLs, the CLI and triggers, and it does not change when you rename the deputy. The Deputies page groups deputies by owner, with archived deputies in a collapsed section.

Missions

Each time you save a mission’s text, Marshal makes a new version. Every run is pinned to the version that produced it, and Recent runs shows the version beside each run.

A version has:

• the prompt, which can use inputs such as {{.repo}}
• inputs, each with an optional default
• a run title template
• a time budget, up to 24 hours

A mission is a draft or active. A draft shows Dry run where an active mission shows Launch. A dry run renders the exact prompt and creates no run, so you can check your inputs and wording. Activate the mission to launch it for real or to let a schedule or trigger start it.

Renaming a mission does not make a new version or change its slug. Deleting a mission archives it first. Restoring an archived mission brings it back as a draft.

Ask for the report you want

Agents know their messages render as markdown on the run page and in Slack, so a mission prompt can ask for tables, diffs and diagrams by name:

Review the open pull requests in {{.repo}}.
Report as a table with the columns PR, Author, Risk and Next step.
For each risk you rate high, show the change you would make as a diff fence.

The run page draws the table and colours the diff. See The run page.

Launch a mission

In the web, open the deputy, find the mission and press Launch. The dialog has the mission’s inputs, a note for this run, Time budget for this run and Compute class for this run. The run appears under Recent runs.

Launch ad-hoc mission sends one prompt that you type, with no saved mission.

From the CLI:

marshal deputies list
marshal deputies missions <deputy-slug>
marshal deputies launch <deputy-slug> --mission <mission-slug> --input repo=acme/web --notes "Focus on the API" --follow

• --input key=value can be repeated, once per key. true, false, null and numbers become typed values, and JSON objects, arrays and quoted strings are accepted.
• --notes adds free text to the prompt for this one launch.
• --follow streams the transcript until the run ends.

Concurrency and the waiting list

Your org and each deputy can limit how many runs of one mission are in flight. A run counts while it is pending, running, waiting on a person or taken over. A parked run does not count.

A launch over the limit waits and starts by itself when a slot frees, oldest first. The deputy page shows it in a Waiting to start card.

• When your install is at the concurrency limit in its license, launches wait the same way and the card shows waiting: install concurrency limit. See Licensing.
• A mission can have up to 100 launches waiting.
• A waiting launch expires after 24 hours.
• marshal runs list shows waiting launches with a ql_ id, and marshal runs cancel <ql_id> cancels one.
• Lowering the limit never stops a run that is already going.

Long runs and compaction

A run that goes on for hours keeps its whole conversation in the agent’s context, and the agent sends all of it again on every turn. Compaction keeps long runs affordable: as the context nears a window you choose, the agent summarises its own history and carries on from the summary.

Compaction is on for every deputy. The default window is 200,000 tokens. It applies to deputy runs only; a run started any other way keeps Claude Code’s own behaviour. The run keeps its task and its instructions, and it finishes the work as before, at a lower cost per turn.

• The window is a target, not an exact trigger. Claude Code decides the moment to compact, so a run can go somewhat past the window before it does.
• A run can be continued, resumed or taken over after it has compacted.
• A run keeps the setting it started with. Changing the deputy affects the next run, and a continuation uses the setting of the run it continues.

Turn compaction off for a deputy that needs its full history in view, such as a reviewer reading a long diff. Off means Marshal sets no window, so the agent follows Claude Code’s built-in behaviour: it compacts only when the context nears the model’s own limit. Choose a larger window, from 100,000 to 1,000,000 tokens, to compact less often. A window can never be larger than the model’s own context.

To change it, open the deputy and select compaction in the About card. The API takes auto_compaction (true or false) and auto_compaction_window (tokens, or null for the default):

curl -X PATCH https://marshal.example.com/api/deputies/<deputy-slug> \
  --header "Authorization: Bearer $MARSHAL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"auto_compaction": true, "auto_compaction_window": 300000}'

The Marshal MCP tools deputies_create and deputies_update take the same two fields.

Runs from a deputy

A deputy’s page lists its recent runs. Each run records how it started: manual, schedule, webhook or API. A scheduled run records which schedule, and a webhook run records the integration and the event. A webhook run records the trigger, not the sender: whoever sends a webhook is not a Marshal identity and gains no authority in Marshal.

When a deputy run needs a decision, the agent asks a person. A mission can name who is asked. See Timeouts and parking.

Insights

Open a deputy and select Insights to see how it is doing. The view shows the deputy’s runs, Success and failure, Runs per day, by trigger, Timeout extensions, Continuations and Engagements by kind, with the median Time to answer on Web, Slack and CLI. Choose 7 days, 30 days or 90 days, and each number compares with the period just before.

The PRs opened, PRs merged and PRs closed tiles count the pull requests this deputy handled on GitHub, each compared with the period before. See Pull request impact.

Every measure is broken down by mission and by mission version. When a new version of a mission starts needing more time or more help, its row shows it next to the version before.

• Who sees it. Everyone who can see a deputy’s runs on its page can open its Insights. Nobody else can.
• Cost. Org owners and admins also see the deputy’s run hours, compute cost, LLM cost and total. Compute covers the CPU, memory and disk of the deputy’s run spaces, at the same prices as the Costs page. Other readers see Insights without cost.
• How it is counted. The numbers use the same definitions as the org’s Deputies tab. A run counts with every continuation as one chain, and the success rate leaves out canceled and in-flight chains. See Admin dashboards.

Webhook, launch queue and takeover counts cover the whole org, so you find them on the Deputies tab.

Suspend, archive and delete

Marshal suspends a team’s deputies when the team is archived.

Configure it

On a deputy

Open the deputy. Its About card has:

A deputy also has an output mode, which says where a run’s output comes from. With transcript (the default), the agent’s final message is the output. With file, Marshal reads /workspace/output.json if the agent wrote one. Set it with the API, using an API key:

curl -X PATCH https://marshal.example.com/api/deputies/<deputy-slug> \
  --header "Authorization: Bearer $MARSHAL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"output_mode": "file"}'

For the org

Org owners and admins set these under Settings > Deputies:

Who can do what

Org owners and admins can see every deputy. See Roles and permissions.

Edge cases

• Only an active deputy launches. A suspended deputy answers with its reason, and an archived one answers that it is archived.
• A schedule or trigger starts only an active mission on an active deputy. A draft can be launched by hand.
• Restoring an archived team does not resume its deputies. Resume them by hand.
• A window you set while compaction is off is kept, and used when you turn compaction back on.

Try it

marshal deputies list
marshal deputies launch <deputy-slug> --mission <mission-slug> --follow

New to deputies? Follow Create a deputy and a mission.

Related

• Deputies
• Use cases
• Schedules and triggers
• The run page
• Timeouts and parking
• Admin dashboards
• Memory
• Owners, teams and scope