Build and run / Harnesses

Run and monitor a harness

Updated 28 Oct 20266 min read

Once a harness is built, you run it from Guardian > Harnesses and follow its work in Guardian > Tasks.

Harness states

StateWhat happens
DraftThe template is saved but nothing runs.
ShadowThe bots run, but every outside change is saved as a draft. Use it to test.
ActiveThe harness works for real.
PausedNothing new runs and every bot of the harness is turned off, including scheduled scans. Events are still recorded, and work continues where it stopped when you resume. A run already in progress finishes.
DisarmedThe harness is switched off and its bots are turned off.

Optimus can start a new harness in shadow and can pause or disarm one. Making a harness active, resuming it and applying changes to a harness that has run before are done by a person on the Harnesses page.

To move a harness between states, use State in the sidebar of the Harnesses page. It lists only the moves allowed from the current state. Making a harness active and disarming it ask you to confirm first; disarming also removes the inputs the harness set up, such as its schedules and listeners. A harness needs an applied template before it can go to shadow or active.

Switch a harness on or off

On the Harnesses page, pick the harness in the sidebar:

  • Enable turns on every bot of the harness and makes it active.
  • Disable pauses the harness and turns off its bots, so no schedule or webhook starts them.

Bots you had turned off yourself before a pause stay off when you resume.

Watch the harness

The Harnesses page shows the harness as a live picture:

  • Triggers and intake: the schedules and webhooks that bring work in, and the bots that record it.
  • Task register: open, closed and failed tasks, with the newest ones.
  • Bots: each bot with its role in the harness and whether it is working.
  • Memory: the memory spaces the bots use.
  • Health and value in the sidebar: problems that need attention, and the work closed without a person against what it cost.
  • Activity: recent tasks. Pick one to open its journey, or use its replay button to play the path it took on the live picture. Back to live returns to live motion; it also comes back on its own a few seconds after the replay ends. Choose 1×, 2× or 4× to change the speed of the motion.

Everything that moves on the picture is real. Each time the page refreshes its counts, a task that reached a new bot flies to it along its route, a new task flies in from intake, and a task that reached an outcome flies back into the task register (and on into the risk register for an accepted risk). Each packet carries the name of the newest task there, or +N when several moved at once. Lines into bots with open work keep a slow flowing dash; lines into idle bots are still.

Send a test event

Use Test event in the sidebar to push one event into the harness, as if one of its inputs had delivered it. Pick the input (or keep the harness default) and optionally paste a JSON payload; leave it empty for a sample event. When the event creates a task, its journey opens; otherwise the event view lists the tasks it created or updated as they appear.

A test item always runs in shadow, even on an active harness: the bots work it but outside changes are only drafted, and a stage whose bot has action or workflow nodes is skipped for the test item.

Run preflight

Preflight in the sidebar checks what the harness needs before it runs: its bots, the accounts they use, and its inputs and memory spaces. Each check shows pass, warning or fail, with the bot it concerns. Applying a change runs the same checks first; see Change the harness.

Follow one task

Open any task in Guardian > Tasks. For a harness task you see:

SectionWhat it shows
Harness stageThe stage the task is in, and which visit this is
JourneyThe path the task took, every rule that was checked and which one matched
What it didEvery real action its runs took, such as a pull request opened, a branch pushed, a message sent or a run cancelled, with links. The platform records these from the tool calls themselves; the bot can't write or change them.
Tool approvalsTools a run asked to use that need a person's approval
Optimus WorkerThe bot's own conversation, where you can see every step and tool call
TimelineEvery change to the task, by whom

Groups of findings

A harness that groups findings shows one row per group in the task list, such as Group · 12 findings. Open the group to see each finding and its own result, such as "9 of 12 resolved". A finding that missed its group shows Waiting for the next group.

You can also group findings yourself:

  • Group findings: in the task list, tick the findings and choose Group selected. They must be open findings of the same harness and application, not already in a group, and not being worked on right now. The group runs once, from the harness's first stage.
  • Take one out: open a finding in a group and choose Take out of group. It waits for the next group, or is worked on its own if the harness doesn't group. The last finding of a group can't be taken out.

You can also ask Optimus to group or ungroup findings.

Approve a tool

When a harness's policy says a tool needs approval, such as merging a pull request, a run that tries it is stopped and the request appears under Tool approvals on the task. Approve it to let the run use the tool once; the run retries.

Give feedback on a result

Under Feedback on a harness task, mark the result as Good fix, Bad fix or False positive. A false positive can be suppressed for a number of days, so the same finding is recorded closed instead of being worked again.

Change the harness

  1. Use Edit in Optimus and describe the change.
  2. Optimus proposes it as a draft. The Harnesses page shows Pending change.
  3. Use Replay 14 days to see how the last two weeks of work would have been routed under the change.
  4. Use Preflight to check the bots, accounts, inputs and memory the change needs.
  5. Apply draft. Tasks already in a stage finish on their current version; their next stage uses the new one.

If preflight fails when you apply, the apply is stopped and the failing checks are shown. Fix them and apply again, or choose Force apply to apply anyway.

Version history and rollback

History lists every applied version, newest first, with who applied it, the note and which sections changed. To roll back, choose Restore as draft on an earlier version. It becomes the Pending change; the live version keeps running until you replay, preflight and apply it.

Org templates

Org templates on the Harnesses page lists the templates your organization rolls out across applications. Each one is proposed as a draft harness on every application whose tags match its selector. Edit one to save a new version: it becomes a pending change on every harness made from it, applied by a person on each. See Roll a harness out with an org template.

Delete a harness

Use Delete in the sidebar. A harness that is still routing work (shadow or active) must be disarmed first. Deleting removes the harness, its template and its version history, then shows a count of everything removed with it. It can't be undone.

Watch from your own tools

You can also follow a harness from an IDE agent or another tool through a read-only connection. See Watch a harness from your IDE.

Next steps

Need a hand with this?Our engineers can walk through it with you on your own stack.